svn commit: r1421893 [5/24] - in /felix/site/trunk/content: ./ documentation/ documentation/community/ documentation/development/ documentation/faqs/ documentation/subprojects/ documentation/subprojects/apache-felix-commons/ documentation/subprojects/a...

[fm...@apache.org]

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-file-install.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-file-install.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-file-install.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-file-install.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,101 @@
+Title: Apache Felix File Install
+
+# Apache Felix File Install
+ 	 
+File Install is a directory based OSGi management agent. It uses a directory in the file system to install and start a bundle when it is first placed there. It updates the bundle when you update the bundle file in the directory and, when the file is deleted, it will stop and uninstall the bundle.
+ 	 
+File Install can do the same for configuration configuration files. This surprisingly simple bundle is very powerful because there are so many programs that work with the file system. For example:
+ 	 
+* If you use Ant, you can just copy the resulting bundle to the watched directory.
+* You can download bundles from the web and directly install them without any extra effort.
+* You can easily drag and drop bundles in and out of the framework.
+ 	 
+## Setup
+ 	 
+The bundle runs on any framework. For its configuration, it will use the following system properties:
+ 	 
+|Property|Default|Description|
+|--|--|--|
+|`felix.fileinstall.poll`|2000 ms|Number of milliseconds between 2 polls of the directory|
+|`felix.fileinstall.dir`|./load|The name of the directory to watch. Several directories can be specified by using a comma separated list.|
+|`felix.fileinstall.log.level`|1|Threshold of logging information|
+|`felix.fileinstall.bundles.new.start`|true|Automatically start newly discovered bundles|
+|`felix.fileinstall.filter`| |A regular expression to be used to filter file names|
+|`felix.fileinstall.tmpdir`| |The name of the temporary directory to use with exploded or transformed bundles (defaults to the temporary dir for the JVM)|
+|`felix.fileinstall.noInitialDelay`|false|Determines if File Install waits `felix.fileinstall.poll` milliseconds before doing an initial scan or not.|
+|`felix.fileinstall.bundles.startTransient`|false|If `true`, File Install will start the bundles transiently.|
+|`felix.fileinstall.bundles.startActivationPolicy`|true|Start bundles with their default activation policy or not|
+|`felix.fileinstall.start.level`|0|If set to a value different from `0`, File Install will set the start level for deployed bundles to that value. If set to `0`, the default framework bundle start level will be used.|
+|`felix.fileinstall.active.level`|0|FileInstall won't scan for files unless the active framework start level is greater than this value|
+|`felix.fileinstall.enableConfigSave`|true|If `false`, File Install will not write back in the file configurations changes. Note that this setting is global and can not be modified per polled directory.|
+|`felix.fileinstall.bundles.updateWithListeners`|false|If `true`, FileInstall will update managed bundles when a new version of an artifact handler is detected.  This detection is performed based on the last modification date of the bundle registering the handler.|
+
+ 	 
+Once started, the values of these properties are printed to the console.
+ 	 
+## Configurations
+ 	 
+Configuration files are plain property files (`java.util.Property`). The format is simple:
+ 	 
+
+    file ::= ( header | comment ) *
+    header ::= <header> ( ':' | '=' ) <value> ( '\<nl> <value> ) *
+    comment ::= '#' <any>
+
+ 	 
+Notice that this model only supports string properties. For example:
+ 	 
+
+    # default port
+    ftp.port = 21
+
+ 	 
+Configuration file names are related to the PID and factory PID. The structure of the file name is as follows:
+ 	 
+
+    filename ::= <pid> ( '-' <subname> )? '.cfg'
+
+ 	 
+If the form is `<pid>.cfg`, the file contains the properties for a Managed Service. The `<pid>` is then the PID of the Managed Service. See the Configuration Admin service for details.
+ 	 
+When a Managed Service Factory is used, the situation is different. The `<pid>` part then describes the PID of the Managed Service Factory. You can pick any `<subname>`, this bundle will then create an instance for the factory for each unique name. For example:
+ 	 
+
+    com.acme.xyz.cfg // configuration for Managed Service
+    // com.acme.xyz
+    com.acme.abc-default.cfg // Managed Service Factory,
+    // creates an instance for com.acme.abc
+
+
+If a configuration managed by File Install is modified, File Install will write the configuration back to a property file to ensure peristence across restarts.
+
+## Property substitution in configuration files
+
+It is possible to use system properties to specify the values of properties in configuration files. This is achieved through system property substitution, which is instigated by using `$\{<property>\`} syntax, where <property> is the name of a system property to substitute.  Bundle context properties will take precedence over system properties if available.
+Example:
+
+
+    ftp.port = ${system.ftp.port}
+
+
+## Watching multiple directories with File Install
+
+Starting with version 3.1.0 it is possible to specify several directories to watch with the system property `felix.fileinstall.dir`; this property can either point to a single directory or a comma separated list of directories. In addition, Apache Felix File Install provides a ManagedServiceFactory to create multiple instances of File Install. Asuming you have a File Install bundle watching a `bundles` folder, creating a new instance is as simple as creating a new configuration file `org.apache.felix.fileinstall-<pid>.cfg` in that folder (substitute <pid> with a unique Id for the new service instance):
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>org.apache.felix.fileinstall-configDir.cfg</B></DIV><DIV class="codeContent panelContent">
+    felix.fileinstall.poll=2000
+    felix.fileinstall.dir=/configDir
+    felix.fileinstall.debug=-1
+    felix.fileinstall.filter=.*\\.cfg
+    felix.fileinstall.bundles.new.start=false
+
+
+## Exploded bundles
+
+Apache Felix File Install has the ability to watch for exploded bundles and automatically update such bundles if the content is changed in any way.  If a watched directory contains a sub directory, its content will be jar'ed and deployed to the OSGi framework.  Any change to a file in this directory or one of its subdirectories will result in the directory to be jar'ed again and the corresponding bundle to be updated.
+
+## Custom artifacts
+
+Apache Felix File Install can support deployment of custom artifacts.  By default, configurations and plain OSGi bundles are supported, but other kind of artifacts can be deployed through custom artifact handlers.
+
+To add support for a custom artifact, a service implementing one of `org.apache.felix.fileinstall.ArtifactListener`'s sub interfaces must be registered in the OSGi registry.

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-framework-security.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-framework-security.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-framework-security.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-framework-security.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,52 @@
+Title: Apache Felix Framework Security
+
+The Felix Framework Security subproject is an implementation of the security part of the OSGi R4.2 core specification.
+
+# Installing
+
+Support for the OSGi r4.2 security specifications including PermissionAdmin and ConditionalPermissionAdmin is provided by the framework.security extension bundle. The bundle provides both, the packages as well as the services when it is installed. 
+
+All that needs to be done is to install the org.apache.felix.framework.security bundle into the framework. 
+
+# Using security
+
+Besides installing the security bundle three properties should be specified:
+* org.osgi.framework.security="osgi"
+* java.security.policy=all.policy
+* org.osgi.framework.trust.repositories=<list of keystores)
+
+The first installs a security manager on framework init (which in combination with the installed security bundle enables security). 
+
+The second, points to a security policy file that gives allpermission like so,
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>all.policy</B></DIV><DIV class="codeContent panelContent">
+    grant {
+     permission java.security.AllPermission;
+    };
+
+
+The third, allows to specify a File.pathseparater separated list of JKS keystores without a password. The certificates found inside the keystores are the trusted root certificates of the framework (setting this property is optional). 
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Example</B></DIV><DIV class="codeContent panelContent">
+    $ java -Djava.security.policy=all.policy -Dorg.osgi.framework.security="osgi" -jar bin/felix.jar
+    
+    Welcome to Felix
+    ================
+    
+    -> install file:org.apache.felix.framework.security.jar
+    -> inspect s c 0
+    System Bundle (0) provides services:
+    ------------------------------------
+    objectClass = org.osgi.service.startlevel.StartLevel
+    service.id = 1
+    ----
+    objectClass = org.osgi.service.packageadmin.PackageAdmin
+    service.id = 2
+    ----
+    objectClass = org.osgi.service.permissionadmin.PermissionAdmin
+    service.id = 3
+    ----
+    objectClass = org.osgi.service.condpermadmin.ConditionalPermissionAdmin
+    service.id = 4
+    
+

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-framework.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-framework.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-framework.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-framework.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,9 @@
+Title: Apache Felix Framework
+
+# Apache Felix Framework
+
+The Felix Framework subproject is an implementation of the OSGi R4.2 core framework specification.
+
+## Framework documentation
+
+{children}

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-and-alternative-java-vms.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-and-alternative-java-vms.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-and-alternative-java-vms.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-and-alternative-java-vms.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,56 @@
+Title: Apache Felix Framework and Alternative Java VMs
+
+# Apache Felix Framework and Alternative Java VMs
+
+This page is intended to document experiences of running Felix on alternative Java VMs. Currently, the following VMs are included:
+
+* [Mika Java Virtual Machine]({{ refs.-mika.path }})
+
+If you have an experience you would like to contribute or edits/additions to an existing platform, please contribute it.
+
+
+
+## Mika Java Virtual Machine
+
+Contributed by [David Lindelöf](http://www.visnet.ch/smartbuildings/running-apache-felix-on-the-unc90-platform/).
+
+We have made Apache Felix run successfully on the [UNC90](http://softgun.sourceforge.net/unc90.shtml) embedded platform and here I'd like to share our experience.
+
+Our UNC90 runs on an ARM9 chip with 16 Mb flash and 32 Mb RAM. It runs the [uClinux](http://uclinux.org/) operating system. The flash is divided in four partitions according to the `linux/drivers/mtd/maps/modarm9.c` file in uClinux's source distribution:
+
+
+    /dev/mtdblock/1: 256 kB for the U-Boot loader
+    /dev/mtdblock/2: 2.75 MB for the uClinux kernel
+    /dev/mtdblock/3: ~3 MB for the root partition
+    /dev/mtdblock/4: ~6.4 MB for user applications, mounted on /mnt
+
+
+We have chosen the Mika Java Virtual Machine, made by [/k/ Embedded Java Solutions](http://k-embedded-java.com/). We install it under `/usr/bin` and `/usr/lib` respectively, and its total footprint is about 1.67 MB. It claims to be compatible with at least Java 1.3, but already includes many features from Java 1.4.
+
+We have installed Felix on the user applications partition under `/mnt/felix`. The framework is then started by a script similar to this:
+
+
+    mika 
+        -Dfelix.config.properties=file:felix.config.properties 
+        -Djava.protocol.handler.pkgs=wonka.net 
+        -jar bin/felix.jar
+
+
+We had to slightly modify the default configuration file. We force the framework to export system packages as if we were running Java 1.4:
+
+
+    org.osgi.framework.system.packages=org.osgi.framework; version=1.3.0, 
+     org.osgi.service.packageadmin; version=1.2.0, 
+     org.osgi.service.startlevel; version=1.0.0, 
+     org.osgi.service.url; version=1.0.0, 
+     ${jre-1.4}
+    # ${jre-${java.specification.version}}
+
+
+The `-Djava.protocol.handler.pkgs=wonka.net` option is necessary if you want to do anything URL-related. See [here](http://felix.apache.org/site/faq.html) for a full discussion. Basically, we must specify the name of a package containing protocol handlers, which defaults to `sun.net.www.protocol`. But with Mika this must be set to `wonka.net` (use `com.acunia.wonka.net` on older versions of Mika).
+
+We have found this setup to be more than satisfactory in terms of stability, performance and memory usage. We have uncovered several bugs in Mika's class library, but the folks at /k/ have always patched them in a timely manner.
+
+## Feedback
+
+Subscribe to the Felix users mailing list by sending a message to [users-subscribe@felix.apache.org]({{ refs.mailto-users-subscribe-felix-apache-org.path }}); after subscribing, email questions or feedback to [users@felix.apache.org|mailto:users@felix.apache.org].
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-and-google-android.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-and-google-android.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-and-google-android.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-and-google-android.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,115 @@
+Title: Apache Felix Framework and Google Android
+
+# Apache Felix Framework and Google Android
+                                                                                                                      
+The purpose of this document is to explain how to use [Apache Felix](http://felix.apache.org) on Google's new mobile phone platform - [Android|http://code.google.com/android].
+ 
+## Dalvik VM
+
+Google Android SDK allows developers to write Java code in order to create Android applications. Instead of a regular Java Virtual Machine that executes this code, a special-purpose virtual machine named Dalvik is being used in order to comply with mobile platform requirements. Dalvik does not use Java bytecode format, but, a tool named dx, included in the Android SDK, transforms the Java class files of Java classes compiled by a regular Java compiler into another class file format (the .dex format) (the conversion is not done at runtime).
+
+## Preparing bundles
+
+Although Felix, since version 1.0.3, has built in support for Android, there are still some things needed to be done in order to successfully make use of it ( you will need to install [Android SDK](http://code.google.com/android/download.html) and you should have <android*SDK*HOME>/tools added to system PATH variable). The zip file available for download has been created in the same manner.
+
+*Step 1*: Each JAR file you use, either as a Felix library or as a bundle, should contain its DEX equivalent. This means that you must first create a DEX file for your JAR:
+
+
+    dx --dex --output=classes.dex JAR_file.jar
+
+
+Then you must add the DEX file to your JAR file:
+
+
+    aapt add JAR_file.jar classes.dex
+
+
+*Step 2*: The processed JARs should be made available to Android by transferring them to the emulator:
+
+
+    emulator &
+    adb push JAR_file.jar path_emulator/JAR_file.jar
+
+
+*Step 3*: Referring to the sample project for a concrete example, these steps are preformed:
+
+
+    osgi-android: /
+    \- bin
+    \- bundle
+    \- conf
+    \- felix.sh
+
+
+Prepare the Felix JAR:
+
+
+    export PATH=<path-to-android>/tools:$PATH
+    cd bin
+    dx --dex --output=classes.dex felix.jar
+    aapt add felix.jar classes.dex
+
+
+Prepare the bundle JARS:
+
+
+    cd bundle
+    dx --dex --output=classes.dex org.apache.felix.shell-1.0.0.jar
+    aapt add org.apache.felix.shell-1.0.0.jar classes.dex
+    dx --dex --output=classes.dex org.apache.felix.shell.tui-1.0.0.jar
+    aapt add org.apache.felix.shell.tui-1.0.0.jar classes.dex
+    dx --dex --output=classes.dex EnglishDictionary.jar
+    aapt add EnglishDictionary.jar classes.dex
+    dx --dex --output=classes.dex FrenchDictionary.jar
+    aapt add FrenchDictionary.jar classes.dex
+    dx --dex --output=classes.dex SpellChecker.jar
+    aapt add SpellChecker.jar classes.dex
+
+
+Transfer all of them to the emulator (note that you need some kind of unix-like shell, such as the Mac OS X terminal or Linux):
+
+
+    cd osgi-android
+    emulator &
+    find * -type f -exec adb push {} /data/felix/{} \;
+
+
+ 
+## Launching Felix
+
+Once you've done that, you should be able to launch Felix and the bundles on Android: start emulator shell, change directory to the location of your Felix files and execute felix.sh.
+
+
+    adb shell
+    cd /data/felix
+    sh felix.sh
+
+
+`felix.sh` contains a Unix shell command that launches Felix main class using the actual runtime of the emulator.
+
+
+    /system/bin/dalvikvm -Xbootclasspath:/system/framework/core.jar \
+      -classpath bin/felix.jar org.apache.felix.main.Main
+
+
+If all went well, you should see the Felix command line shell now. Type "help" for further instructions.
+
+You may now install and launch EnglishDictionary, FrenchDictionary, and SpellChecker bundles to test how Felix is working. These are all examples from the Apache Felix OSGi tutorial and correspond to [Apache Felix Tutorial Example 2]({{ refs.apache-felix-tutorial-example-2.path }}), [Apache Felix Tutorial Example 2b], and [Apache Felix Tutorial Example 5] respectively.
+
+    * *EnglishDictionary* - supplies a Dictionary service implementation with the following collection of words "welcome", "to", "the", "osgi", "tutorial"
+    * *FrenchDictionary* - supplies a Dictionary service implementation with the following collection of words "bienvenue", "au", "tutoriel", "osgi"
+    * *SpellChecker* - supplies a spell checker that retrieves the first Dictionary implementation it finds and checks if the word you've entered is in the dictionary or not.
+
+
+    start file:bundle/EnglishDictionary.jar
+    start file:bundle/FrenchDictionary.jar
+    start file:bundle/SpellChecker.jar
+
+
+## Embedding Felix
+
+Apache Felix can also be integrated with an Android application. To achieve this, you need to embed Felix into `onCreate()` method of your Activity class (see Android docs for more details on how to use an Activity) and process your bundles as shown above.
+ 
+## Download
+
+The project zip file [osgi-android.zip]({{ refs.documentation-osgi-android-felix-1-4-android-sdk-1-0-zip.path }})
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-bundle-cache.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-bundle-cache.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-bundle-cache.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-bundle-cache.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,68 @@
+Title: Apache Felix Framework Bundle Cache
+
+# Apache Felix Framework Bundle Cache
+
+* [Introduction]({{ refs.-introduction.path }})
+* [Default Behavior]({{ refs.-default-behavior.path }})
+* [Configuring Default Behavior]({{ refs.-configuring-behavior.path }})
+
+
+
+# Introduction
+
+The OSGi specification states that the framework must cache bundles and their run-time state, but it does not explicitly define how this should be done. As a result, each OSGi framework implementation is likely to cache bundles differently. This document describes in detail how the Felix framework handles bundle caching by default and also describes the mechanisms to modify this default behavior.
+
+
+
+# Default Behavior
+
+Since the OSGi R4.2 specification, the standard framework launching and embedding API requires that frameworks should use "reasonable defaults" for all configuration properties so it is possible to start a framework without any configuration. One such default value is the location of the framework bundle cache. When the Felix framework is start, it creates a bundle cache directory, called `felix-cache`, in the current working directory by default. All bundle information is saved inside the bundle cache directory.
+
+The structure of a bundle cache directory is reasonably simple; it contains a directory for each bundle, where the directory name corresponds to the bundle identifier number. Each bundle directory contains a file for the bundle's location, identifier, start level, state, and a directory containing the bundle JAR file and any extracted embedded JAR files or native libraries if any exist. As an example, the bundle cache directory for a bundle containing an embedded JAR file and a native library looks like this:
+
+
+       ${user.dir}
+          felix-cache/
+             bundle4/
+                bundle.id
+                bundle.lastmodified
+                bundle.location
+                bundle.startlevel
+                bundle.state
+                data/
+                version0.0/
+                   revision.location
+                   bundle.jar
+                   bundle.jar-embedded/
+                      embedded.jar
+                   bundle.jar-lib/
+                      0/
+                         libnative.so
+
+
+The above directory structure indicates that the imaginary bundle is cached in the `felix-cache` in the current working directory and "4" is its bundle identifier. Additionally, besides the bundle JAR file, the bundle has one embedded JAR file and one native library. The naming convention is rather straightforward and consistent, although the directory structure may seem rather indirect. The precise details behind the rationale for the directory structure around embedded JAR files and native libraries is not so important, but suffice it to say it results from how fragment content can be shared among hosts.
+
+All cached bundle directories will follow the basic pattern displayed above, except for the names of the embedded JAR files and native libraries. Embedded JAR files and native libraries use the names specified in the bundle manifest and may also include sub-directories to avoid name clashes. The naming convention for the directory containing the bundle JAR file, `version0.0`, requires further explanation.
+
+The bundle JAR directory uses a numbering scheme to keep track of the number of times a bundle is updated and the number of times it is refreshed; the name of the directory maps like this: `version<refresh-count>.<revision-count>`. The reasoning behind this is tricky. It is necessary to keep track of the revision count because the OSGi specification requires when a bundle is updated that the update takes effect immediately. However, it also requires that old packages from older revisions of the updated bundle are kept available until a refresh of the framework is performed. As a result, it is possible for multiple revisions of a bundle JAR to be providing packages at a given time.
+
+For example, if a bundle provides package `foo` and it is updated and now provides packages `foo` and `bar`, then after the update `foo` will be supplied from the older revision and `bar` will be supplied from the newer revision. This is possible for any number of updates, thus the bundle JAR directory must keep each revision around until a refresh is performed. Such "revision directories" are generally only run-time directories and are removed when the framework is shutdown or refreshed, they are not intended to exist for multiple sessions of execution.
+
+To illustrate, upon initial installation, the bundle JAR file is placed into a revision directory named `revision0.0`. When an update is performed, the updated bundle JAR file is placed in a directory named `revision0.1`. If another update is performed without a refresh of the framework, the newer revision will be placed into a directory named `revision0.2` and so on. When the framework is refreshed or shutdown, all revision directories are purged from the bundle cache and only the most recent revision directory is maintained.
+
+Simply purging the old revision directories may appear adequate for refreshing the framework, but it is not due to how the JVM handles native libraries. When a native library is loaded it is associated with a specific class loader; no other class loader can load the same native library. The uniqueness of a native library is determined by its absolute path in the file system. Consequently, when the framework is refreshed, it is necessary to recreate the class loaders for all refreshed bundles. If a refreshed bundle has a native library, then this would result in an exception since the native library is still associated with the prior class loader; the refresh counter remedies this situation.
+
+After purging all old revision directories, the current revision directory is renamed based on the current refresh count. By renaming the directory, it is possible to re-load the native library since its path in the file system has changed. The old class loaders and native libraries will eventually be garbage collected. The current refresh count is stored in a file, called `refresh.counter`, in the bundle's directory. To illustrate, if a bundle was updated and has two revision directories, `revision0.0` and `revision0.1`, after a refresh the older revision directory will be deleted and the newest revision directory will be renamed to `revision1.0`. If the bundle is refresh again, its revision directory will become `revision2.0` and so on. Note: Bundles may be refreshed when they are updated or when they depend on other bundles that have been updated; either way it is necessary to increment the refresh count and rename the revision directory during a refresh operation.
+
+
+
+# Configuring Default Behavior
+
+It is possible to modify the default behavior of Felix' bundle cache by setting certain configuration properties; see the [usage document]({{ refs.apache-felix-framework-usage-documentation-configuring-framework.path }}) for information on how to set configuration properties for Felix. Felix' bundle cache recognizes the following configuration properties:
+
+* `org.osgi.framework.storage` \- Sets the directory to use as the bundle cache; by default bundle cache directory is `felix-cache` in the current working directory. The value should be a valid directory name. The directory name can be either absolute or relative. Relative directory names are relative to the current working directory. The specified directory will be created if it does not exist.
+* `org.osgi.framework.storage.clean` \- Determines whether the bundle cache is flushed. The value can either be "`none`" or "`onFirstInit`", where "`none`" does not flush the bundle cache and "`onFirstInit`" flushes the bundle cache when the framework instance is first initialized. The default value is "`none`".
+* `felix.cache.rootdir` \- Sets the root directory to use to calculate the bundle cache directory for relative directory names. If `org.osgi.framework.storage` is set to a relative name, by default it is relative to the current working directory. If this property is set, then it will be calculated as being relative to the specified root directory.
+* `felix.cache.bufsize` \- Sets the buffer size to be used by the cache; the default value is 4096. The integer value of this string provides control over the size of the internal buffer of the disk cache for performance reasons.
+
+To be clear, if a relative bundle cache directory is specified then the absolute location of the bundle cache directory is computed like this: `$\{felix.cache.rootdir}+$\{org.osgi.framework.storage`}, where `felix.cache.rootdir` has the default value of the current working directory. If `$\{org.osgi.framework.storage`} is specified as absolute, then it is used as the location of the bundle cache. If the bundle cache directory does not exist, it is created.
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-configuration-properties.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-configuration-properties.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-configuration-properties.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-configuration-properties.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,82 @@
+Title: Apache Felix Framework Configuration Properties
+
+# Apache Felix Framework Configuration Properties
+
+* [Overview]({{ refs.-overview.path }})
+* [Framework configuration properties]({{ refs.-framework.path }})
+* [Launcher configuration properties]({{ refs.-launcher.path }})
+* [Mirgrating from earlier versions]({{ refs.-migrating.path }})
+* [Feedback]({{ refs.-feedback.path }})
+
+
+
+## Overview
+
+This document describes the various configuration properties related to the Apache Felix Framework. Technically, there are framework properties and launcher properties. If you are using the Felix Framework JAR file (i.e., `org.apache.felix.framework-x.y.x.jar`), then you can only use framework properties. On the other hand, if you are using the Felix Main launcher JAR (i.e., `felix.jar` or `org.apache.felix.main-x.y.z.jar`), then you can use both framework and launcher properties. This document will describe both sets of properties.
+
+Note that the framework does not use system properties to find its configuration properties, it only consults the map passed into its constructor. In contrast to bundles, which use `BundleContext.getProperty()`, which exposes both configuration and system properties at execution time. In the case of overlap, the configuration properties override system properties. As a convenience, if you are using the Felix launcher, it will copy all configuration properties it finds in the system properties to the configuration map passed into the framework constructor, which allows you to set configuration properties on the command line. This feature is *not* available if you are just using the Felix framework JAR file.
+
+
+
+## Framework configuration properties
+
+The following configuration properties are for the framework (properties starting with "`felix`" are specific to Felix, while those starting with "`org.osgi`" are standard OSGi properties):
+
+* `org.osgi.framework.executionenvironment` \- Sets the OSGi execution environment for the framework. The framework tries to set this to a reasonable default value. If you specify a value, it overrides the framework default. Refer to the OSGi specification for appropriate execution environment values.
+* `org.osgi.framework.storage` \- Sets the directory to use as the bundle cache; by default the bundle cache directory is `felix-cache` in the current working directory. The value should be a valid directory name. The directory name can be either absolute or relative. Relative directory names are relative to the current working directory. The specified directory will be created if it does not exist.
+* `felix.cache.rootdir` \- Sets the root directory used to calculate the bundle cache directory for relative directory names. If `org.osgi.framework.storage` is set to a relative name, by default it is relative to the current working directory. If this property is set, then it will be calculated as being relative to the specified root directory.
+* `org.osgi.framework.storage.clean` \- Determines whether the bundle cache is flushed. The value can either be "`none`" or "`onFirstInit`", where "`none`" does not flush the bundle cache and "`onFirstInit`" flushes the bundle cache when the framework instance is first initialized. The default value is "`none`".
+* `felix.cache.filelimit` \- The integer value of this string sets an upper limit on how many files the cache will open. The default value is zero, which means there is no limit. (Since 4.0)
+* `felix.cache.locking` \- Enables or disables bundle cache locking, which is used to prevent concurrent access to the bundle cache. This is enabled by default, but on older/smaller JVMs file channel locking is not available; set this property to `false` to disable it.
+* `felix.cache.bufsize` \- Sets the buffer size to be used by the cache; the default value is 4096. The integer value of this string provides control over the size of the internal buffer of the disk cache for performance reasons.
+* `org.osgi.framework.system.packages` \- Specifies a comma-delimited list of packages that should be exported via the System Bundle from the framework class loader. The framework will set this to a reasonable default. If the value is specified, it replaces any default value.
+* `org.osgi.framework.system.packages.extra` \- Specifies a comma-delimited list of packages that should be exported via the System Bundle from the framework class loader in addition to the packages in `org.osgi.framework.system.packages`. The default value is empty. If a value is specified, it is appended to the list of default or specified packages in `org.osgi.framework.system.packages`.
+* `org.osgi.framework.bootdelegation` \- Specifies a comma-delimited list of packages that should be made implicitly available to all bundles from the parent class loader. It is recommended not to use this property since it breaks modularity. The default value is empty.
+* `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`.
+* `felix.bootdelegation.implicit` \- Specifies whether the framework should try to guess when to implicitly boot delegate to ease integration with external code. The default value is `true`.
+* `felix.systembundle.activators` \- 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. (This property cannot be set in the configuration file since it requires instances; it can only be passed into Felix' constructor directly.)
+* `felix.log.logger` \- An instance of `Logger` that the framework uses as its default logger. (This property cannot be set in the configuration file since it requires an instance; it can only be passed into Felix' constructor directly.)
+* `felix.log.level` \- An integer value indicating the degree of logging reported by the framework; the higher the value the more logging is reported. If zero ('0') is specified, then logging is turned off completely. The log levels match those specified in the OSGi Log Service (i.e., 1 = error, 2 = warning, 3 = information, and 4 = debug). The default value is 1.
+* `org.osgi.framework.startlevel.beginning` \- The initial start level of the framework once it starts execution; the default value is 1.
+* `felix.startlevel.bundle` \- The default start level for newly installed bundles; the default value is 1.
+* `felix.service.urlhandlers` \- Flag to indicate whether to activate the URL Handlers service for the framework instance; the default value is `true`. Activating the URL Handlers service will result in the `URL.setURLStreamHandlerFactory()` and `URLConnection.setContentHandlerFactory()` being called.
+
+
+
+## Launcher configuration properties
+
+The following configuration properties are for the launcher:
+
+* `felix.auto.deploy.dir` \- Specifies the auto-deploy directory from which bundles are automatically deployed at framework startup. The default is the `bundle/` directory of the current directory.
+* `felix.auto.deploy.action` \- Specifies a comma-delimited list of actions to be performed on bundle JAR files found in the auto-deploy directory. The possible actions are `install`, `update`, `start`, and `uninstall`. An undefined or blank value is equivalent to disabling auto-deploy processing; there is no default value, so this value must be defined to enable it.
+* `felix.auto.install.<n>` \- Space-delimited list of bundle URLs to automatically install when Felix 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 Felix is started, where `<n>` is the start level into which the bundle will be installed (e.g., `felix.auto.start.2`).
+* `felix.shutdown.hook` \- Specifies whether the launcher should install a shutdown hook to cleanly shutdown the framework on process exit. The default value is `true`.
+
+
+
+## Migrating from Earlier Versions
+
+Apache Felix Framework `2.0.0` introduced significant configuration property changes. This section describes the differences from older versions of the framework.
+
+* *Removed*
+** `felix.embedded.execution` \- No longer needed, since the framework now never calls `System.exit()`; the creator of the framework is now always responsible for exiting the VM.
+** `felix.strict.osgi` \- No longer needed, since all non-specification features have been removed.
+** `felix.cache.dir` \- No longer needed, since Felix no longer uses bundle cache profiles for saving sets of bundles.
+** `felix.cache.profile` \- No longer needed, since the framework no longer uses bundle cache profiles for saving sets of bundles.
+** `felix.fragment.validation` \- No longer needed, since the framework supports fragments.
+* *Renamed*
+** `felix.cache.profiledir` \- The equivalent of this property is now named `org.osgi.framework.storage`.
+** `felix.startlevel.framework` \- The equivalent of this property is now named `org.osgi.framework.startlevel.beginning`.
+* *Introduced*
+** `org.osgi.framework.system.packages.extra` \- New property, as described above, added to align with standard framework API.
+** `org.osgi.framework.storage.clean` \- New property, as described above, added to align with standard framework API.
+** `felix.cache.rootdir` \- Introduced as a result of removing bundle profiles to help resolve relative bundle cache directories.
+
+For the most part, these changes are minor and previous behavior achieved from older configuration properties is either easily attained with the new properties or no longer necessary.
+
+
+
+## Feedback
+
+Subscribe to the Felix users mailing list by sending a message to [users-subscribe@felix.apache.org]({{ refs.mailto-users-subscribe-felix-apache-org.path }}); after subscribing, email questions or feedback to [users@felix.apache.org|mailto:users@felix.apache.org].
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-faq.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-faq.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-faq.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-faq.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,62 @@
+Title: Apache Felix Framework FAQ
+
+# Apache Felix Framework Frequently Asked Questions
+
+[TOC]
+
+## Is the Felix framework compliant with the OSGi specification?
+
+Refer to the [Apache Felix Framework OSGi R4.2 CT Results]({{ refs.apache-felix-framework-osgi-r4-2-ct-results.path }}) document.
+
+## If I use bundles from Felix, will my application be tied to the Felix framework?
+
+See the answer in the [OSGi FAQ]({{ refs.apache-felix-osgi-faq-felix-dependencies.path }}).
+
+## When I update my bundle, why are my bundle's old classes still being used?
+
+See the answer in the [OSGi FAQ]({{ refs.apache-felix-osgi-faq-bundle-not-updated.path }}).
+
+## Why do I get an "Unknown protocol: http" exception when I run Felix on a non-Sun JRE?
+
+Felix installs the URL Handlers service by default. If you do not want this service you can disable it, by setting the `felix.service.urlhandlers` property to `false` in the `config.properties` file. It is not recommended to disable this, but the main reason for doing so it because the URL Handlers implementation invokes methods to set the singleton factories for URL stream and content handler factories. Assuming that you want to use URL Handlers service, you must configure it if you aren't running on the standard Sun JRE.
+
+The URL Handlers service extends the standard Java URL stream and content handler mechanism to work in an OSGi environment. The way that built-in URL protocol and content handlers are discovered is by probing packages for the appropriate classes to handle the protocol/content. For example, the default package for Sun protocol handlers is:
+
+
+    sun.net.www.protocol
+
+
+If someone tries to create a URL for the "http" protocol, then the class to handle the protocol will be:
+
+
+    sun.net.www.protocol.http.Handler
+
+
+A similar process is followed for content handlers, whose default package is:
+
+
+    sun.net.www.content
+
+
+If you are running on a VM that is different than Sun's, then you must determine what are the default packages used for its protocol and content handlers. Once you know this information, then you can configure Felix to use those packages instead of the default one. You can configure Felix by setting the following system properties:
+
+
+    java.protocol.handler.pkgs
+
+
+and
+
+
+    java.content.handler.pkgs
+
+
+The value of these properties is a list of "|" delimited package names to be searched for protocol and content handlers, respectively. See the Java documentation for [stream](http://java.sun.com/javase/6/docs/api/java/net/URL.html#URL(java.lang.String,%20java.lang.String,%20int,%20java.lang.String)) and [content|http://java.sun.com/javase/6/docs/api/java/net/URLConnection.html#getContent()] handlers for more information.
+
+There are two ways to set these system properties. The first way is using the standard `-D<property>=<value>` syntax when executing `java` or if you are using Felix' standard `Main.java` launcher, you can put the system properties into the `conf/system.properties` file so that they get set automatically each time you execute Felix.
+
+## What is the daemon status of framework created threads?
+
+The framework creates a few threads for handling specific tasks, such as event delivery or handling start level change requests. All framework threads are explicitly started as daemon threads except the event dispatcher thread. The logic behind this is that the event dispatcher thread should exit when it is done delivering events. However, if an application is hosting an instance of the framework, it is possible to make the event dispatcher thread a daemon by starting your framework instance from a daemon thread, in which case the event dispatcher thread will inherit this setting.
+
+For bundle developers, it is probably best to explicitly define any created threads as daemon or non-daemon to avoid any ambiguity.
+

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-launching-and-embedding.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-launching-and-embedding.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-launching-and-embedding.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-framework/apache-felix-framework-launching-and-embedding.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,786 @@
+Title: Apache Felix Framework Launching and Embedding
+
+# Apache Felix Framework Launching and Embedding
+
+*\[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.\]({{ refs.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.path }})*
+
+* [Introduction]({{ refs.-introduction.path }})
+* [OSGi Launching and Embedding API Overview]({{ refs.-overview.path }})
+** [Creating and Configuring the Framework Instance]({{ refs.-creating-and-configuring.path }})
+** [Starting the Framework Instance]({{ refs.-starting-instance.path }})
+** [Stopping the Framework Instance]({{ refs.-stopping-instance.path }})
+* [Launching Felix]({{ refs.-launching.path }})
+** [Standard Felix Launcher]({{ refs.-standard-launcher.path }})
+** [Custom Felix Launcher]({{ refs.-custom-launcher.path }})
+* [Embedding Felix]({{ refs.-embedding.path }})
+** [Host/Felix Interaction]({{ refs.-host-interaction.path }})
+** [Providing Host Application Services]({{ refs.-host-services.path }})
+** [Using Services Provided by Bundles]({{ refs.-host-service-usage.path }})
+*** [Using Bundle Services via Reflection]({{ refs.-service-reflection.path }})
+*** [Other Approaches]({{ refs.-service-other.path }})
+* [Caveat]({{ refs.-caveat.path }})
+* [Feedback]({{ refs.-feedback.path }})
+
+
+
+# Introduction
+
+The Apache Felix Framework is intended to be easily launchable and embeddable. For example, the Felix framework implementation avoids the use of system properties for configuration, since these are globals and can cause interference if multiple framework instances are created in the same VM. The framework also tries to multiplex singleton facilities, like the URL stream handler factory. The goal is to make it possible to use the framework in a variety of scenarios; however, this is still just a goal. In other words, this is a work in progress and if any issues arise, it would be greatly appreciated if they are brought to the attention of the Felix community. The next section provides an overview of the standard OSGi launching and embedding API for frameworks, while the remainder of the document is divided into two sections, one focusing on how to launch Felix and one focusing on how to embed Felix into a host application.
+
+
+
+# OSGi Launching and Embedding API Overview
+
+The Felix framework is implemented by the `org.apache.felix.framework.Felix` class or just `Felix` for short. As part of the R4.2 OSGi specification, the launching and embedding API of the OSGi framework has been standardized. The approach is to have the framework implement the `org.osgi.framework.launch.Framework` interface, which extends the `org.osgi.framework.Bundle` interface. These interfaces provide the necessary means to launch and manage framework instances. The `Bundle` interface is defined as:
+
+
+    public interface Bundle
+    {
+        BundleContext getBundleContext();
+        long getBundleId();
+        URL getEntry(String name);
+        Enumeration getEntryPaths(String path);
+        Enumeration findEntries(String path, String filePattern, boolean recurse);
+        Dictionary getHeaders();
+        Dictionary getHeaders(String locale);
+        long getLastModified();
+        String getLocation();
+        URL getResource(String name);
+        Enumeration getResources(String name) throws IOException;
+        ServiceReference[] getRegisteredServices();
+        ServiceReference[] getServicesInUse();
+        int getState();
+        String getSymbolicName();
+        Version getVersion();
+        boolean hasPermission(Object obj);
+        Class loadClass(String name) throws ClassNotFoundException;
+        void start() throws BundleException;
+        void stop() throws BundleException;
+        void uninstall() throws BundleException;
+        void update() throws BundleException;
+        void update(InputStream is) throws BundleException;
+    }
+
+
+The `Framework` interface is defined as:
+
+
+    public interface Framework extends Bundle
+    {
+        void init();
+        FrameworkEvent waitForStop(long timeout);
+    }
+
+
+To actually construct a framework instance, the R4.2 specification defines the `FrameworkFactory` interface:
+
+
+    public interface FrameworkFactory
+    {
+        Framework newFramework(Map config);
+    }
+
+
+The framework factory can be used to create configured framework instances. It is obtained following the standard `META-INF/services` approach.
+
+
+
+## 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]({{ refs.apache-felix-framework-configuration-properties.path }}) 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.
+
+<div class="warning" markdown="1">
+**WARNING**
+Felix configuration properties have change considerably starting from `1.4.0`; if you are upgrading from an earlier version, the [configuration property document]({{ refs.apache-felix-framework-configuration-properties-migrating.path }}) describes the configuration property changes.
+</div>
+
+
+
+## Starting the Framework Instance
+
+The `start()` method is used to start the framework instance. If the `init()` method was not invoked prior to calling `start()`, then it is invoked by `start()`. The two methods result in two different framework state transitions:
+
+* `init()` results in the framework instance in the `Bundle.STARTING` state.
+* `start()` results in the framework instance in the `Bundle.ACTIVE` state.
+
+The `init()` method is necessary since the framework does not have a `BundleContext` when it is first created, so a transition to the `Bundle.STARTING` state is required to acquire its context (via `Bundle.getBundleContext()`) for performing various tasks, such as installing bundles. Note that the Felix framework also provides the `felix.systembundle.activators` property that serves a similar purpose, but is not standard. After the `init()` method completes, the follow actions have been performed:
+
+* Event handling is enabled.
+* The security manager is installed if it is enabled.
+* The framework is set to start level 0.
+* All bundles in the bundle caches are reified and their state is set to `Bundle.INSTALLED`.
+* The framework gets a valid `BundleContext`.
+* All framework-provided services are made available (e.g., PackageAdmin, StartLevel, etc.).
+* The framework enters the `Bundle.STARTING` state.
+
+A call to `start()` is necessary to start the framework instance, if the `init()` method is invoked manually. Invoking `init()` or `start()` on an already started framework as no effect.
+
+
+
+## Stopping the Framework Instance
+
+To stop the framework instance, invoke the `stop()` method, which will asynchronously stop the framework. To know when the framework has finished its shutdown sequence, use the `waitForStop()` method to wait until it is complete. A stopped framework will be in the `Bundle.RESOLVED` state. It is possible to restart the framework, using the normal combination of `init()`/`start()` methods as previously described.
+
+
+
+# Launching a Framework
+
+Launching a framework is fairly simple and involves only four steps:
+
+1. Define some configuration properties.
+1. Obtain framework factory.
+1. Use factory to create framework with the configuration properties.
+1. Invoke the `Framework.start()` method.
+
+In reality, the first step is optional, since all properties will have reasonable defaults, but if you are creating a launcher you will generally want to more than that, such as automatically installing and starting bundles when you start the framework instance. The default Felix launcher defines reusable functionality to automatically install and/or start bundles upon framework startup; see the [usage document]({{ refs.apache-felix-framework-usage-documentation-configuring-felix.path }}) for more information on configuring the Felix framework and on the various configuration properties.
+
+The remainder of this section describes how the standard Felix launcher works as well as how to create a custom launcher.
+
+
+
+## Standard Felix Framework Launcher
+
+The standard Felix framework launcher is very simple and is not intended to solve every possible requirement; it is intended to work for most standard situations. Most special launching requirements should be resolved by creating a custom launcher. This section describes how the standard launcher works. The following code represents the complete `main()` method of the standard launcher, each numbered comment will be described in more detail below:
+
+
+    public static void main(String[] args) throws Exception
+    {
+        // (1) Check for command line arguments and verify usage.
+        String bundleDir = null;
+        String cacheDir = null;
+        boolean expectBundleDir = false;
+        for (int i = 0; i < args.length; i++)
+        {
+            if (args[i].equals(BUNDLE_DIR_SWITCH))
+            {
+                expectBundleDir = true;
+            }
+            else if (expectBundleDir)
+            {
+                bundleDir = args[i];
+                expectBundleDir = false;
+            }
+            else
+            {
+                cacheDir = args[i];
+            }
+        }
+    
+        if ((args.length > 3) || (expectBundleDir && bundleDir == null))
+        {
+            System.out.println("Usage: [-b <bundle-deploy-dir>] [<bundle-cache-dir>]");
+            System.exit(0);
+        }
+    
+        // (2) Load system properties.
+        Main.loadSystemProperties();
+    
+        // (3) Read configuration properties.
+        Properties configProps = Main.loadConfigProperties();
+        if (configProps == null)
+        {
+            System.err.println("No " + CONFIG_PROPERTIES_FILE_VALUE + " found.");
+            configProps = new Properties();
+        }
+    
+        // (4) Copy framework properties from the system properties.
+        Main.copySystemProperties(configProps);
+            
+        // (5) Use the specified auto-deploy directory over default.
+        if (bundleDir != null)
+        {
+            configProps.setProperty(AutoProcessor.AUTO_DEPLOY_DIR_PROPERY, bundleDir);
+        }
+    
+        // (6) Use the specified bundle cache directory over default.
+        if (cacheDir != null)
+        {
+            configProps.setProperty(Constants.FRAMEWORK_STORAGE, cacheDir);
+        }
+    
+        // (7) Add a shutdown hook to clean stop the framework.
+        String enableHook = configProps.getProperty(SHUTDOWN_HOOK_PROP);
+        if ((enableHook == null) || !enableHook.equalsIgnoreCase("false"))
+        {
+            Runtime.getRuntime().addShutdownHook(new Thread("Felix Shutdown Hook") {
+                public void run()
+                {
+                    try
+                    {
+                        if (m_fwk != null)
+                        {
+                            m_fwk.stop();
+                            m_fwk.waitForStop(0);
+                        }
+                    }
+                    catch (Exception ex)
+                    {
+                        System.err.println("Error stopping framework: " + ex);
+                    }
+                }
+            });
+        }
+    
+        try
+        {
+            // (8) Create an instance and initialize the framework.
+            FrameworkFactory factory = getFrameworkFactory();
+            m_fwk = factory.newFramework(configProps);
+            m_fwk.init();
+            // (9) Use the system bundle context to process the auto-deploy
+            // and auto-install/auto-start properties.
+            AutoProcessor.process(configProps, m_fwk.getBundleContext());
+            // (10) Start the framework.
+            m_fwk.start();
+            // (11) Wait for framework to stop to exit the VM.
+            m_fwk.waitForStop(0);
+            System.exit(0);
+        }
+        catch (Exception ex)
+        {
+            System.err.println("Could not create framework: " + ex);
+            ex.printStackTrace();
+            System.exit(0);
+        }
+    }
+
+
+The general steps of the standard launcher are quite straightforward:
+
+1. The launcher supports setting the auto-deploy directory (with the `-b` switch) and setting the bundle cache path with a single argument, so check for this and issue a usage message it there are more than one arguments.
+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.
+1. 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 framework 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.
+1. For convenience, any configuration properties that are set as system properties are copied into the set of configuration properties. This provide an easy way to add to or override configuration properties specified in the `config.properties` file, since the Felix instance will never look at system properties for configuration.
+1. If the `-b` switch was used to specify an auto-deploy directory, then use that to set the value of `felix.auto.deploy.dir`.
+1. If a single command-line argument is specified, then use that to set the value of `org.osgi.framework.storage`; relative paths are relative to the current directory unless the `felix.cache.rootdir` property is set.
+1. Add a shutdown hook to cleanly stop the framework, unless the hook is disabled.
+1. Create a framework instance using the `FrameworkFactory` passing in the configuration properties, then initialize the factory instance; see the [custom launcher example]({{ refs.-custom-launcher.path }}) below to see how the META-INF/services `FrameworkFactory` is obtained.
+1. Use `org.apache.felix.main.AutoProcessor`, which will automatically deploy any bundles in the auto-deploy directory as well as bundles specified in the `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]({{ refs.apache-felix-framework-usage-documentation-configuring-framework.path }}) and [bundle auto-deploy|Apache Felix Framework Usage Documentation#auto-deploy].
+1. Invoke `waitForStop()` to wait for the framework to stop to force the VM to exit; this is necessary because the framework never calls `System.exit()` and some libraries (e.g., Swing) create threads that will not allow the VM to exit.
+
+The framework is not active until the `start()` method is called. If no shell bundles are installed and started or if there is difficulty locating the shell bundles specified in the auto-start property, 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.
+
+
+
+## Custom Framework Launcher
+
+This section creates a bare-bones launcher to demonstrate the minimum requirements for creating an interactive launcher for the Felix framework. This example uses the standard Gogo shell bundles for interactivity, but any other bundles could be used instead. This example launcher project has the following directory structure:
+
+
+    launcher/
+       lib/
+          org.apache.felix.main-3.0.0.jar
+       bundle/
+          org.apache.felix.gogo.command-0.6.0.jar
+          org.apache.felix.gogo.runtime-0.6.0.jar
+          org.apache.felix.gogo.shell-0.6.0.jar
+       src/
+          example/
+             Main.java
+
+
+The `lib/` directory contains Felix' main JAR file, which also contains the OSGi core interfaces. The main JAR file is used so that we can reuse the default launcher's auto-install/auto-start configuration property handling; if these capabilities are not needed, then it would be possible to use the framework JAR file instead of the main JAR file. The `bundle/` directory contains the shell service and textual shell interface bundles that will be used for interacting with the framework instance. Note: If you do not launch the framework with interactive bundles, it will appear as if the framework instance is hung, but it is actually just sitting there waiting for someone to tell it to do something. The `src/example/` directory contains the following `Main.java` file, which is a very simplistic framework launcher.
+
+
+    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.");
+        }
+    }
+
+
+This launcher relies on the default behavior of `AutoProcessor` to automatically deploy the shell bundles. This simple, generic launcher provides a good starting point if the default Felix launcher is not sufficient. Since very few configuration properties are specified, the default values are used. For the bundle auto-deploy directory, "`bundle`" in the current directory is used, while for the framework bundle cache, "`felix-cache`" in the current directory is used.
+
+By breaking down the above source code into small chunks, it is quite easy to see what is going on.
+
+
+                m_fwk = getFrameworkFactory().newFramework(null);
+                m_fwk.init()
+
+
+These steps get a the framework factory service and use it to create a framework instance with a default configuration. Once the framework instance is created, it is initialized with `init()`.
+
+
+                AutoProcessor.process(null, m_fwk.getBundleContext());
+
+
+The `AutorProcessor` will automatically deploy bundles in the auto-deploy directory and any referenced from the auto-install/start properties. Since we are using an empty configuration, the auto-deploy directory is the `bundle` directory in the current directory and there are no auto properties. Therefore, in this case, the shell bundles will be installed.
+
+
+                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.
+
+
+        private static FrameworkFactory getFrameworkFactory() throws Exception
+        {
+            ...
+        }
+
+
+This method retrieves the framework factory service by doing a META-INF/services resource lookup, which it can use to obtain the concrete class name for the factory. If you are using Java 6, then you can use the `ServiceLoader` API in the JRE to further simplify the factory service lookup.
+
+The following command compiles the launcher when run from the root directory of the launcher project:
+
+
+    javac -d . -classpath lib/org.apache.felix.main-3.0.0.jar src/example/Main.java
+
+
+After executing this command, an `example/` directory is created in the current directory, which contains the generated class file. The following command executes the simple launcher when run from the root directory of the launcher project:
+
+
+    java -cp .:lib/org.apache.felix.main-3.0.0.jar example.Main
+
+
+After executing this command, a "`felix-cache/`" directory is created that contains the cached bundles, which were installed from the `bundle/` directory.
+
+
+
+# Embedding the Felix Framework
+
+Embedding the Felix framework into a host application is a simple way to provide a sophisticated extensibility mechanism (i.e., a plugin system) to the host application. Embedding the Felix framework is very similar to launching it as described above, the main difference is that the host application typically wants to interact with the framework instance and/or installed bundles/services from the outside. This is fairly easy to achieve, but there are some subtle issues to understand. This section presents the mechanisms for embedding Felix into a host application and the issues in doing so.
+
+
+
+## Host/Felix Interaction
+
+In the section on [launching]({{ refs.-launching.path }}) the framework above, the `Felix` class accepts a configuration property called `felix.systembundle.activators`, which is a list of bundle activator instances. These bundle activator instances provide a convenient way for host applications to interact with the Felix framework.
+
+<div class="warning" markdown="1">
+**WARNING**
+The `felix.systembundle.activators` configuration property is specific to the Felix framework implementation. If you want your code to work with other framework implementations, you should call `init()` on the framework instance and use `getBundleContext()` directly. Otherwise, the approach would be very similar.
+</div>
+
+Each activator instance passed into the constructor effectively becomes part of the system bundle. This means that the `start()`/`stop()` methods of each activator instance in the list gets invoked when the system bundle's activator `start()`/`stop()` methods gets invoked, respectively. Each activator instance will be given the system bundle's `BundleContext` object so that they can interact with the framework. Consider following snippet of a bundle activator:
+
+
+    public class HostActivator implements BundleActivator
+    {
+        private BundleContext m_context = null;
+    
+        public void start(BundleContext context)
+        {
+            m_context = context;
+        }
+    
+        public void stop(BundleContext context)
+        {
+            m_context = null;
+        }
+    
+        public Bundle[] getBundles()
+        {
+            if (m_context != null)
+            {
+                return m_context.getBundles();
+            }
+            return null;
+        }
+    }
+
+
+Given the above bundle activator, it is now possible to embed the Felix framework into a host application and interact with it as the following snippet illustrates:
+
+
+    public class HostApplication
+    {
+        private HostActivator m_activator = null;
+        private Felix m_felix = null;
+    
+        public HostApplication()
+        {
+            // Create a configuration property map.
+            Map config = new HashMap();
+            // Create host activator;
+            m_activator = new HostActivator();
+            List list = new ArrayList();
+            list.add(m_activator);
+            configMap.put(FelixConstants.SYSTEMBUNDLE_ACTIVATORS_PROP, list);
+    
+            try
+            {
+                // Now create an instance of the framework with
+                // our configuration properties.
+                m_felix = new Felix(config);
+                // Now start Felix instance.
+                m_felix.start();
+            }
+            catch (Exception ex)
+            {
+                System.err.println("Could not create framework: " + ex);
+                ex.printStackTrace();
+            }
+        }
+    
+        public Bundle[] getInstalledBundles()
+        {
+            // Use the system bundle activator to gain external
+            // access to the set of installed bundles.
+            return m_activator.getBundles();
+        }
+    
+        public void shutdownApplication()
+        {
+            // Shut down the felix framework when stopping the
+            // host application.
+            m_felix.stop();
+            m_felix.waitForStop(0);
+        }
+    }
+
+
+Notice how the `HostApplication.getInstalledBundles()` method uses its activator instance to get access to the system bundle's context in order to interact with the embedded Felix framework instance. This approach provides the foundation for all interaction between the host application and the embedded framework instance.
+
+
+
+## Providing Host Application Services
+
+Providing services from the host application to bundles inside the embedded Felix framework instance follows the basic approach laid out in [above]({{ refs.-host-interaction.path }}). The main complication for providing a host application service to bundles is the fact that both the host application and the bundles must be using the same class definitions for the service interface classes. Since the host application cannot import classes from a bundle, this means that the service interface classes *must* be accessible on the class path, typically as part of the host application itself. The host application then must export the service interface package via the system bundle so that bundles installed into the embedded framework instance can import it. This is achieved using the `org.osgi.framework.system.packages.extra` configuration property previously presented.
+
+Consider the follow simple property lookup service:
+
+
+    package host.service.lookup;
+    
+    public interface Lookup
+    {
+        public Object lookup(String name);
+    }
+
+
+This package is simply part of the host application, which is potentially packaged into a JAR file and started with the "`java -jar`" command. Now consider the following host application bundle activator, which will be used to register/unregister the property lookup service when the embedded framework instance starts/stops:
+
+
+    package host.core;
+    
+    import java.util.Map;
+    import org.osgi.framework.BundleActivator;
+    import org.osgi.framework.BundleContext;
+    import org.osgi.framework.ServiceRegistration;
+    import host.service.lookup;
+    
+    public class HostActivator implements BundleActivator
+    {
+        private Map m_lookupMap = null;
+        private BundleContext m_context = null;
+        private ServiceRegistration m_registration = null;
+    
+        public HostActivator(Map lookupMap)
+        {
+            // Save a reference to the service's backing store.
+            m_lookupMap = lookupMap;
+        }
+    
+        public void start(BundleContext context)
+        {
+            // Save a reference to the bundle context.
+            m_context = context;
+            // Create a property lookup service implementation.
+            Lookup lookup = new Lookup() {
+                public Object lookup(String name)
+                {
+                    return m_lookupMap.get(name);
+                }
+            };
+            // Register the property lookup service and save
+            // the service registration.
+            m_registration = m_context.registerService(
+                Lookup.class.getName(), lookup, null);
+        }
+    
+        public void stop(BundleContext context)
+        {
+            // Unregister the property lookup service.
+            m_registration.unregister();
+            m_context = null;
+        }
+    }
+
+
+Given the above host application bundle activator, the following code snippet shows how the host application could create an embedded version of the Felix framework and provide the property lookup service to installed bundles:
+
+
+    package host.core;
+    
+    import java.util.List;
+    import java.util.ArrayList;
+    import java.util.Map;
+    import java.util.HashMap;
+    import host.service.lookup.Lookup;
+    import org.apache.felix.framework.Felix;
+    import org.apache.felix.framework.util.FelixConstants;
+    import org.osgi.framework.Constants;
+    
+    public class HostApplication
+    {
+        private HostActivator m_activator = null;
+        private Felix m_felix = null;
+        private Map m_lookupMap = new HashMap();
+    
+        public HostApplication()
+        {
+            // Initialize the map for the property lookup service.
+            m_lookupMap.put("name1", "value1");
+    
+            m_lookupMap.put("name2", "value2");
+            m_lookupMap.put("name3", "value3");
+            m_lookupMap.put("name4", "value4");
+    
+            // Create a configuration property map.
+            Map configMap = new HashMap();
+            // Export the host provided service interface package.
+            configMap.put(Constants.FRAMEWORK_SYSTEMPACKAGES_EXTRA,
+                "host.service.lookup; version=1.0.0");
+            // Create host activator;
+            m_activator = new HostActivator(m_lookupMap);
+            List list = new ArrayList();
+            list.add(m_activator);
+            configMap.put(FelixConstants.SYSTEMBUNDLE_ACTIVATORS_PROP, list);
+    
+            try
+            {
+                // Now create an instance of the framework with
+                // our configuration properties.
+                m_felix = new Felix(configMap);
+                // Now start Felix instance.
+                m_felix.start();
+            }
+            catch (Exception ex)
+            {
+                System.err.println("Could not create framework: " + ex);
+                ex.printStackTrace();
+            }
+        }
+    
+        public void shutdownApplication()
+        {
+            // Shut down the felix framework when stopping the
+            // host application.
+            m_felix.stop();
+            m_felix.waitForStop(0);
+        }
+    }
+
+
+Rather than having the host application bundle activator register the service, it is also possible for the the host application to simply get the bundle context from the bundle activator and register the service directly, but the presented approach is perhaps a little cleaner since it allows the host application to register/unregister the service when the system bundle starts/stops.
+
+
+
+## Using Services Provided by Bundles
+
+Using services provided by bundles follows the same general approach of using a host application bundle activator. The main complication for the host application using a service from a bundle is the fact that both the host application and the bundle must be using the same class definitions for the service interface classes. Since the host application cannot import classes from a bundle, this means that the service interface classes *must* be accessible on the class path, typically as part of the host application itself. The host application then must export the service interface package via the system bundle so that bundles installed into the embedded framework instance can import it. This is achieved using the `org.osgi.framework.system.packages.extra` configuration property previously presented.
+
+Consider the following simple command service interface for which bundles provide implementations, such as might be used to create an extensible interactive shell:
+
+
+    package host.service.command;
+    
+    public class Command
+    {
+        public String getName();
+        public String getDescription();
+        public boolean execute(String commandline);
+    }
+
+
+This package is simply part of the host application, which is potentially packaged into a JAR file and started with the "`java -jar`" command. Now consider the previously introduced host application bundle activator below, which simply provides access to the system bundle context:
+
+
+    package host.core;
+    
+    import org.osgi.framework.BundleActivator;
+    import org.osgi.framework.BundleContext;
+    
+    public class HostActivator implements BundleActivator
+    {
+        private BundleContext m_context = null;
+    
+        public void start(BundleContext context)
+        {
+            m_context = context;
+        }
+    
+        public void stop(BundleContext context)
+        {
+            m_context = null;
+        }
+    
+        public BundleContext getContext()
+        {
+            return m_context;
+        }
+    }
+
+
+With this bundle activator, the host application can use command services provided by bundles installed inside its embedded Felix framework instance. The following code snippet illustrates one possible approach:
+
+
+    package host.core;
+    
+    import java.util.List;
+    import java.util.ArrayList;
+    import java.util.Map;
+    import host.service.command.Command;
+    import org.apache.felix.framework.Felix;
+    import org.apache.felix.framework.util.FelixConstants;
+    import org.apache.felix.framework.cache.BundleCache;
+    import org.osgi.framework.Constants;
+    import org.osgi.util.tracker.ServiceTracker;
+    
+    public class HostApplication
+    {
+        private HostActivator m_activator = null;
+        private Felix m_felix = null;
+        private ServiceTracker m_tracker = null;
+    
+        public HostApplication()
+        {
+            // Create a configuration property map.
+            Map configMap = new HashMap();
+            // Export the host provided service interface package.
+            configMap.put(Constants.FRAMEWORK_SYSTEMPACKAGES_EXTRA,
+                "host.service.command; version=1.0.0");
+            // Create host activator;
+            m_activator = new HostActivator();
+            List list = new ArrayList();
+            list.add(m_activator);
+            configMap.put(FelixConstants.SYSTEMBUNDLE_ACTIVATORS_PROP, list);
+    
+            try
+            {
+                // Now create an instance of the framework with
+                // our configuration properties.
+                m_felix = new Felix(configMap);
+                // Now start Felix instance.
+                m_felix.start();
+            }
+            catch (Exception ex)
+            {
+                System.err.println("Could not create framework: " + ex);
+                ex.printStackTrace();
+            }
+    
+            m_tracker = new ServiceTracker(
+                m_activator.getContext(), Command.class.getName(), null);
+            m_tracker.open();
+        }
+    
+        public boolean execute(String name, String commandline)
+        {
+            // See if any of the currently tracked command services
+            // match the specified command name, if so then execute it.
+            Object[] services = m_tracker.getServices();
+            for (int i = 0; (services != null) && (i < services.length); i++)
+            {
+                try
+                {
+                    if (((Command) services[i]).getName().equals(name))
+                    {
+                        return ((Command) services[i]).execute(commandline);
+                    }
+                }
+                catch (Exception ex)
+                {
+                    // Since the services returned by the tracker could become
+                    // invalid at any moment, we will catch all exceptions, log
+                    // a message, and then ignore faulty services.
+                    System.err.println(ex);
+                }
+            }
+            return false;
+        }
+    
+        public void shutdownApplication()
+        {
+            // Shut down the felix framework when stopping the
+            // host application.
+            m_felix.stop();
+            m_felix.waitForStop(0);
+        }
+    }
+
+
+The above example is overly simplistic with respect to concurrency issues and error conditions, but it demonstrates the overall approach for using bundle-provided services from the host application.
+
+
+
+### Using Bundle Services via Reflection
+
+It possible for the host application to use services provided by bundles without having access to the service interface classes and thus not needing to put the service interface classes on the class path. To do this, the host application uses the same general approach to acquire the system bundle context object, which it can use to look up service objects. Using either an LDAP filter or the service interface class name, the host application can retrieve the service object and then use standard Java reflection to invoke methods on the service object.
+
+
+
+### Other Approaches
+
+The [Transloader](http://code.google.com/p/transloader/) project is another attempt at dealing with issues of classes loaded from different class loaders and may be of interest.
+
+
+
+# Caveat
+
+The code in this document has not been thoroughly tested nor even compiled and may be out of date with respect to the current Felix source code. If you find errors please report them so the that they can be corrected.
+
+
+
+## Feedback
+
+Subscribe to the Felix users mailing list by sending a message to [users-subscribe@felix.apache.org]({{ refs.mailto-users-subscribe-felix-apache-org.path }}); after subscribing, email questions or feedback to [users@felix.apache.org|mailto:users@felix.apache.org].
\ No newline at end of file