Add framework distribution.
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@910114 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/main.distribution/doc/apache-felix-framework-usage-documentation.html b/main.distribution/doc/apache-felix-framework-usage-documentation.html
new file mode 100644
index 0000000..b3b725c
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-usage-documentation.html
@@ -0,0 +1,399 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html><head>
+
+
+
+ <title>Apache Felix - Apache Felix Framework Usage Documentation</title>
+ <link rel="stylesheet" href="apache-felix-framework-usage-documentation_files/site.css" type="text/css" media="all">
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ </head><body>
+ <div class="title"><div class="logo"><a href="http://felix.apache.org/site/index.html"><img alt="Apache Felix" src="apache-felix-framework-usage-documentation_files/logo.png" border="0"></a></div><div class="header"><a href="http://www.apache.org/"><img alt="Apache" src="apache-felix-framework-usage-documentation_files/apache.png" border="0"></a></div></div>
+ <div class="menu">
+<ul>
+ <li><a href="http://felix.apache.org/site/news.html" title="news">news</a></li>
+ <li><a href="http://felix.apache.org/site/license.html" title="license">license</a></li>
+ <li><a href="http://felix.apache.org/site/downloads.cgi" rel="nofollow">downloads</a></li>
+ <li><a href="http://felix.apache.org/site/documentation.html" title="documentation">documentation</a></li>
+ <li><a href="http://felix.apache.org/site/mailinglists.html" title="mailinglists">mailing lists</a></li>
+ <li><a href="http://felix.apache.org/site/contributing.html" title="Contributing">contributing</a></li>
+ <li><a href="http://www.apache.org/" rel="nofollow">asf</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html" rel="nofollow">sponsorship</a></li>
+ <li><a href="http://www.apache.org/foundation/thanks.html" rel="nofollow">sponsors</a>
+<!-- ApacheCon Ad -->
+<iframe src="apache-felix-framework-usage-documentation_files/button.html" style="border-width: 0pt; float: left;" frameborder="0" height="135" scrolling="no" width="135"></iframe>
+<p style="height: 100px;">
+<!-- ApacheCon Ad -->
+</p></li></ul> </div>
+ <div class="main">
+<h1><a name="ApacheFelixFrameworkUsageDocumentation-ApacheFelixFrameworkUsageDocumentation"></a>Apache Felix Framework Usage Documentation</h1>
+
+<ul>
+ <li><a href="#ApacheFelixFrameworkUsageDocumentation-downloadingframework">Downloading the Framework</a></li>
+ <li><a href="#ApacheFelixFrameworkUsageDocumentation-startingframework">Starting the Framework</a></li>
+ <li><a href="#ApacheFelixFrameworkUsageDocumentation-frameworkshell">Framework Shell</a>
+ <ul>
+ <li><a href="#ApacheFelixFrameworkUsageDocumentation-installingbundles">Installing Bundles</a></li>
+ <li><a href="#ApacheFelixFrameworkUsageDocumentation-installingbundlesproxies">Web Proxy Issues when Installing Bundles</a></li>
+ </ul>
+ </li>
+ <li><a href="#ApacheFelixFrameworkUsageDocumentation-autodeploy">Bundle Auto-Deploy</a></li>
+ <li><a href="#ApacheFelixFrameworkUsageDocumentation-configuringframework">Configuring the Framework</a>
+ <ul>
+ <li><a href="#ApacheFelixFrameworkUsageDocumentation-migrating">Migrating from Earlier Versions</a></li>
+ <li><a href="#ApacheFelixFrameworkUsageDocumentation-propertysubstitution">System Property Substitution</a></li>
+ </ul>
+ </li>
+ <li><a href="#ApacheFelixFrameworkUsageDocumentation-configuringbundles">Configuring Bundles</a></li>
+ <li><a href="#ApacheFelixFrameworkUsageDocumentation-feedback">Feedback</a></li>
+</ul>
+
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-downloadingframework"></a></p>
+
+<h2><a name="ApacheFelixFrameworkUsageDocumentation-DownloadingtheFramework"></a>Downloading the Framework</h2>
+
+<p>Go to the <a href="http://felix.apache.org/site/downloads.html" title="downloads">downloads</a> page and download the latest Felix framework distribution.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-startingframework"></a></p>
+
+<h2><a name="ApacheFelixFrameworkUsageDocumentation-StartingtheFramework"></a>Starting the Framework</h2>
+
+<p>Start the framework from the installation directory by typing:</p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>java -jar bin/felix.jar
+</pre>
+</div></div>
+
+<p>The framework launcher starts the framework and installs a bundles contained in the <tt>bundle</tt>
+directory of the current directory. By default, the bundle directory
+contains a simple text-based shell to interact with the framework.
+Bundles installed into the framework are copied into a bundle cache
+directory for subsequent executions. By default, the framework creates
+a cache directory, called <tt>felix-cache</tt>, in your current working directory; this behavior is configurable, see the <a href="http://felix.apache.org/site/apache-felix-framework-bundle-cache.html" title="Apache Felix Framework Bundle Cache">Apache Felix Framework Bundle Cache</a> document for more details.</p>
+
+<p>If you want to start the framework using a different bundle cache directory, you can do so like this:</p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>java -jar bin/felix.jar <cache-path>
+</pre>
+</div></div>
+
+<p>Where <tt><cache-path></tt> is the path you want to use as the
+bundle cache. If you specify a relative cache path, then it will be
+treated as relative to the current working directory.</p>
+
+<div class="panelMacro"><table class="infoMacro"><colgroup><col width="24"><col></colgroup><tbody><tr><td valign="top"><img src="apache-felix-framework-usage-documentation_files/information.gif" alt="" align="absmiddle" border="0" height="16" width="16"></td><td><b>Useful Information</b><br><p>Previous
+versions of the framework prompted for a profile name when executed.
+The profile name was used to create a directory inside <tt>.felix/</tt>
+in the user home directory. This approach allowed users to have
+different sets of bundles for different purposes, e.g., testing,
+production, etc. If this behavior is still desired, it is very easy to
+mimic. Modify <tt>conf/config.properties</tt> to include "<tt>felix.cache.rootdir=${user.home}/.felix</tt>". Now, if you start Felix with something like "<tt>java -jar bin/felix.jar foo</tt>", it will use "<tt>${user.home}/.felix/foo/</tt>" as the bundle cache directory, where "<tt>${user.home</tt>}" is automatically substituted with the appropriate system property by the launcher.</p></td></tr></tbody></table></div>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-frameworkshell"></a></p>
+
+<h2><a name="ApacheFelixFrameworkUsageDocumentation-FrameworkShell"></a>Framework Shell</h2>
+
+<p>The main way to interact with the framework is via its shell. Felix'
+shell is implemented as an OSGi service that, be default, uses a simple
+text-based user interface. After starting the framework, type <tt>help</tt> into the shell to see the list of the available commands and <tt>help <command-name></tt> to get help for a specific command.</p>
+
+<p>To install bundles, use the <tt>install</tt> command, which is described in more detail in the next <a href="#ApacheFelixFrameworkUsageDocumentation-installingbundles">sub-section</a>. To view all currently installed bundles, use the <tt>ps</tt> command. To stop the framework type <tt>stop 0</tt>
+to stop the System Bundle; any installed bundles will automatically be
+reloaded (and potentially restarted) the next time you launch with the
+associated cache.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-installingbundles"></a></p>
+
+<h3><a name="ApacheFelixFrameworkUsageDocumentation-InstallingBundles"></a>Installing Bundles</h3>
+
+<p>A bundle is the OSGi term for a component for the OSGi framework. A
+bundle is simply a JAR file containing a manifest and some combination
+of Java classes, embedded JAR files, native code, and resources. A
+bundle may provide some specific functionality for the user or it may
+implement a service that other bundles can use; bundles can only use
+functionality from other bundles through shared services and packages.</p>
+
+<p>The Felix framework is packaged with three bundles, which are located in the <tt>bundle/</tt>
+directory of the framework installation directory. There are bundles
+for the Felix shell service, a text-based shell service user interface,
+and a bundle repository service. In addition to these bundles, the
+bundle repository services provides access to other bundles for easy
+installation. The bundle repository service provides a shell command,
+named <tt>obr</tt>, to access available bundles; refer to the <a href="http://felix.apache.org/site/apache-felix-osgi-bundle-repository.html" title="Apache Felix OSGi Bundle Repository">Apache Felix OSGi Bundle Repository</a> for more information.</p>
+
+<p>Before installing any bundles, it is important to understand how
+bundles are manually deployed into the framework. Bundles are deployed
+in two stages; first they are installed, then they are started. To
+install a bundle use the <tt>install</tt> shell command followed by a bundle URL. For example, to install a <tt>bundle.jar</tt> bundle you type (assuming you have started Felix from its installation directory):</p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>install file:/path/to/bundle/bundle.jar
+</pre>
+</div></div>
+
+<p>Once a bundle is installed, it can then be started by using the <tt>start</tt> command and the bundle identifier of the desired bundle. The <tt>ps</tt>
+shell command is used to list all installed bundles and to obtain the
+bundle's identifier. The following Felix shell session capture
+illustrates how to start the <tt>bundle.jar</tt> bundle:</p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>-> install [file:bundle/simple]
+-> ps
+START LEVEL 1
+ ID State Level Name
+[ 0] [Active ] [ 0] System Bundle (2.0.0)
+[ 1] [Active ] [ 1] Shell Service (1.4.0)
+[ 2] [Active ] [ 1] Shell TUI (1.4.0)
+[ 3] [Active ] [ 1] Bundle Repository (1.4.0)
+[ 4] [Installed ] [ 1] Bundle Example (1.0.0)
+-> start 4
+Hello from Bundle 4.
+->
+</pre>
+</div></div>
+
+<p>The <tt>stop</tt> command is used to stop a bundle and the <tt>uninstall</tt> command is used to remove a bundle from the bundle cache. As an alternative to using the <tt>install</tt> and <tt>start</tt> commands explicitly, it is also possible to install and start a bundle in one step by using the <tt>start</tt> command with a bundle URL.</p>
+
+<p>Bundles can be updated using the <tt>update</tt> command. The update
+command allows you to specify an URL from which to retrieve the updated
+bundle, but if one is not specified it will try to update the bundle
+from the bundle's <tt>Bundle-UpdateLocation</tt> manifest attribute, if present, or the bundle's original location URL.</p>
+
+<p><b>Important:</b> When you <tt>update</tt> or <tt>uninstall</tt> a
+bundle, the changes appear to take effect immediately, but in reality
+the changes are only partially enacted. If a bundle is updated or
+uninstalled and it was exporting packages, these packages are not
+removed until the framework is refreshed using the <tt>PackageAdmin</tt> service. The Felix shell offers a convenient <tt>refresh</tt> command for this purpose.</p>
+
+<p>For an introduction to writing bundles and services, refer to the Felix bundle tutorial.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-installingbundlesproxies"></a></p>
+
+<h3><a name="ApacheFelixFrameworkUsageDocumentation-WebProxyIssueswhenInstallingBundles"></a>Web Proxy Issues when Installing Bundles</h3>
+
+<p>If you use a proxy for Web access, then you may run into difficulty
+using the Felix shell to install bundles from a remote URL. To remedy
+this situation, certain system properties must be set to make Felix
+work with your proxy. These properties are:</p>
+
+<ul>
+ <li><tt>http.proxyHost</tt> - the name of the proxy host.</li>
+ <li><tt>http.proxyPort</tt> - the port of the proxy host.</li>
+ <li><tt>http.proxyAuth</tt>
+- the user name and password to use when connecting to the proxy; this
+string should be the user name and password separated by a colon (e.g.,
+<tt>rickhall:mypassword</tt>).</li>
+</ul>
+
+
+<p>These system properties can be set directly on the command line when starting the JVM using the standard "<tt>-D<prop>=<value></tt>" syntax or you can put them in the <tt>lib/system.properties</tt> file of your Felix installation; see the next section on <a href="#ApacheFelixFrameworkUsageDocumentation-configuringframework">configuring Felix</a> for more information.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-autodeploy"></a></p>
+
+<h2><a name="ApacheFelixFrameworkUsageDocumentation-BundleAutoDeploy"></a>Bundle Auto-Deploy</h2>
+
+<p>To minimize the amount of configuration necessary to install bundles
+when you launch the framework, the Felix launcher uses the concept of
+an "auto-deploy" directory. The Felix launcher deploys all bundles in
+the auto-deploy directory into the framework instance during startup.
+By default, the auto-deploy directory is "<tt>bundle</tt>" in the current directory, but it can be specified on the command line like this:</p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>java -jar bin/felix.jar -b /path/to/dir
+</pre>
+</div></div>
+
+<p>Specifying an auto-deploy directory replaces the default directory,
+it does not augment it. The default deployment actions performed on the
+bundles in the auto-deploy directory are: install, update, and start.
+Both the location of the auto-deploy directory and the deployment
+actions performed can be controlled by the following configuration
+properties, respectively:</p>
+
+<ul>
+ <li><tt>felix.auto.deploy.dir</tt> - Specifies the auto-deploy directory from which bundles are automatically deploy at framework startup. The default is the <tt>bundle/</tt> directory of the current directory.</li>
+ <li><tt>felix.auto.deploy.action</tt>
+- Specifies the auto-deploy actions to be found on bundle JAR files
+found in the auto-deploy directory. The possible actions are <tt>install</tt>, <tt>update</tt>, <tt>start</tt>, and <tt>uninstall</tt>.
+If no actions are specified, then the auto-deploy directory is not
+processed. There is no default value for this property, but the default
+<tt>config.properties</tt> file installed with the Felix framework sets the value to <tt>install</tt>, <tt>update</tt>, and <tt>start</tt>.</li>
+</ul>
+
+
+<p>The next section describes how to set and use configuration properties.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-configuringframework"></a></p>
+
+<h2><a name="ApacheFelixFrameworkUsageDocumentation-ConfiguringtheFramework"></a>Configuring the Framework</h2>
+
+<p>Both the Felix framework and the launcher use configuration
+properties to alter their default behavior. The framework can only be
+configured by passing properties into its constructor, but the launcher
+provides a mechanism to configure the framework via a property file.
+The launcher The Felix framework uses properties to configure certain
+aspects of its behavior. The framework launcher reads configuration
+properties from <tt>conf/config.properties</tt>. This file uses standard Java property file syntax.</p>
+
+<p>The launcher also supports setting system properties via the <tt>conf/system.properties</tt>
+file. This file is purely for convenience when you need to repeatedly
+set system properties when running the framework. While the framework
+itself does not look at system properties, the launcher does copy any
+framework configuration properties found in the system properties into
+the framework configuration map, also for your convenience.</p>
+
+<p>It is possible to specify a different locations for these property files for the system properties file by using the <tt>felix.config.properties</tt> and <tt>felix.system.properties</tt> system properties when executing the framework. For example:</p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>java -Dfelix.config.properties=file:/home/rickhall/config.properties -jar bin/felix.jar
+</pre>
+</div></div>
+
+<p>Configuration and system properties are accessible at run time via <tt>BundleContext.getProperty()</tt>, but configuration properties override system properties.</p>
+
+<p>The following configuration properties are specifically for the launcher:</p>
+
+<ul>
+ <li><tt>felix.auto.deploy.dir</tt> - Specifies the auto-deploy directory from which bundles are automatically deploy at framework startup. The default is the <tt>bundle/</tt> directory of the current directory.</li>
+ <li><tt>felix.auto.deploy.action</tt>
+- Specifies the auto-deploy actions to be found on bundle JAR files
+found in the auto-deploy directory. The possible actions are <tt>install</tt>, <tt>update</tt>, <tt>start</tt>, and <tt>uninstall</tt>. An undefined or blank value is equivalent to disabling auto-deploy processing.</li>
+ <li><tt>felix.auto.install.<n></tt> - Space-delimited list of bundle URLs to automatically install when Felix is started, where <tt><n></tt> is the start level into which the bundle will be installed (e.g., <tt>felix.auto.install.2</tt>).</li>
+ <li><tt>felix.auto.start.<n></tt> - Space-delimited list of bundle URLs to automatically install and start when Felix is started, where <tt><n></tt> is the start level into which the bundle will be installed (e.g., <tt>felix.auto.start.2</tt>).</li>
+ <li><tt>felix.shutdown.hook</tt>
+- Specifies whether the launcher should install a shutdown hook to
+cleanly shutdown the framework on process exit. The default value is <tt>true</tt>.</li>
+</ul>
+
+
+<p>The following configuration properties are specifically for the framework (properties starting with "<tt>felix</tt>" are specific to Felix, while those starting with "<tt>org.osgi</tt>" are standard OSGi properties):</p>
+
+<ul>
+ <li><tt>org.osgi.framework.storage</tt> - Sets the directory to use as the bundle cache; by default bundle cache directory is <tt>felix-cache</tt>
+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.</li>
+ <li><tt>felix.cache.rootdir</tt> - Sets the root directory to use to calculate the bundle cache directory for relative directory names. If <tt>org.osgi.framework.storage</tt>
+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.</li>
+ <li><tt>org.osgi.framework.storage.clean</tt> - Determines whether the bundle cache is flushed. The value can either be "<tt>none</tt>" or "<tt>onFirstInit</tt>", where "<tt>none</tt>" does not flush the bundle cache and "<tt>onFirstInit</tt>" flushes the bundle cache when the framework instance is first initialized. The default value is "<tt>none</tt>".</li>
+ <li><tt>felix.cache.bufsize</tt>
+- 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.</li>
+ <li><tt>org.osgi.framework.system.packages</tt>
+- Specifies a comma-delimited list of packages that should be exported
+via the System Bundle from the parent class loader. The framework will
+set this to a reasonable default. If the value is specified, it
+replaces any default value.</li>
+ <li><tt>org.osgi.framework.system.packages.extra</tt>
+- Specifies a comma-delimited list of packages that should be exported
+via the System Bundle from the parent class loader in addition to the
+packages in <tt>org.osgi.framework.system.packages</tt>. The default value is empty. If a value is specified, it is appended to the list of default or specified packages in <tt>org.osgi.framework.system.packages</tt>.</li>
+ <li><tt>org.osgi.framework.bootdelegation</tt>
+- 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.</li>
+ <li><tt>felix.bootdelegation.implicit</tt>
+- Specifies whether the framework should try to guess when to
+implicitly boot delegate to ease integration with external code. The
+default value is <tt>true</tt>.</li>
+ <li><tt>felix.systembundle.activators</tt> - A <tt>List</tt> of <tt>BundleActivator</tt>
+instances that are started/stopped when the System Bundle is
+started/stopped. The specified instances will receive the System
+Bundle's <tt>BundleContext</tt> when invoked. (This property cannot be
+set in the configuration file since it requires instances; it can only
+be passed into Felix' constructor directly.)</li>
+ <li><tt>felix.log.logger</tt> - An instance of <tt>Logger</tt>
+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.)</li>
+ <li><tt>felix.log.level</tt>
+- 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.</li>
+ <li><tt>org.osgi.framework.startlevel.beginning</tt> - The initial start level of the framework once it starts execution; the default value is 1.</li>
+ <li><tt>felix.startlevel.bundle</tt> - The default start level for newly installed bundles; the default value is 1.</li>
+ <li><tt>felix.service.urlhandlers</tt> - Flag to indicate whether to activate the URL Handlers service for the framework instance; the default value is "<tt>true</tt>". Activating the URL Handlers service will result in the <tt>URL.setURLStreamHandlerFactory()</tt> and <tt>URLConnection.setContentHandlerFactory()</tt> being called.</li>
+ <li><tt>felix.fragment.validation</tt> - Determines if installing unsupported fragment bundles throws an exception or logs a warning. Possible values are "<tt>exception</tt>" or "<tt>warning</tt>". The default value is "<tt>exception</tt>".</li>
+</ul>
+
+
+<p>The Felix framework installation contains a default <tt>conf/config.properties</tt> file for automatically starting the shell-related bundles.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-migrating"></a></p>
+
+<h3><a name="ApacheFelixFrameworkUsageDocumentation-MigratingfromEarlierVersions"></a>Migrating from Earlier Versions</h3>
+
+<p>Apache Felix Framework <tt>1.4.0</tt> introduced some configuration property changes. This section describes the differences from older versions of the framework.</p>
+
+<ul>
+ <li><b>Removed</b>
+ <ul>
+ <li><tt>felix.embedded.execution</tt> - No longer needed, since the framework now never calls <tt>System.exit()</tt>; the creator of the framework is now always responsible for exiting the VM.</li>
+ <li><tt>felix.strict.osgi</tt> - No longer needed, since all non-specification features have been removed.</li>
+ <li><tt>felix.cache.dir</tt> - No longer needed, since Felix no longer uses bundle cache profiles for saving sets of bundles.</li>
+ <li><tt>felix.cache.profile</tt> - No longer needed, since Felix no longer uses bundle cache profiles for saving sets of bundles.</li>
+ </ul>
+ </li>
+ <li><b>Renamed</b>
+ <ul>
+ <li><tt>felix.cache.profiledir</tt> - The equivalent of this property is now named <tt>org.osgi.framework.storage</tt>.</li>
+ <li><tt>felix.startlevel.framework</tt> - The equivalent of this property is now named <tt>org.osgi.framework.startlevel.beginning</tt>.</li>
+ </ul>
+ </li>
+ <li><b>Introduced</b>
+ <ul>
+ <li><tt>org.osgi.framework.system.packages.extra</tt> - New property, as described above, added to align with standard framework API.</li>
+ <li><tt>org.osgi.framework.storage.clean</tt> - New property, as described above, added to align with standard framework API.</li>
+ <li><tt>felix.cache.rootdir</tt> - Introduced as a result of removing bundle profiles to help resolve relative bundle cache directories.</li>
+ <li><tt>felix.fragment.validation</tt> - Introduced to control fragment validation, since the default behavior introduced in <tt>1.2.0</tt> of throwing an exception for fragments using unsupported features was causing issues for some users.</li>
+ </ul>
+ </li>
+</ul>
+
+
+<p>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.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-propertysubstitution"></a></p>
+
+<h3><a name="ApacheFelixFrameworkUsageDocumentation-SystemPropertySubstituion"></a>System Property Substituion</h3>
+
+<p>It is possible to use system properties to specify the values of properties in the <tt>conf/config.properties</tt> file. This is achieved through system property substitution, which is instigated by using <tt>${<property></tt>} syntax, where <tt><property></tt>
+is the name of a system property to substitute. When such a property
+value is retrieved by a bundle, the system property value will be
+substituted into the bundle property value as appropriate. It is
+possible to have nested system property substitution, in which case the
+inner-most property is substituted first, then the next inner most,
+until reaching the outer most.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-configuringbundles"></a></p>
+
+<h2><a name="ApacheFelixFrameworkUsageDocumentation-ConfiguringBundles"></a>Configuring Bundles</h2>
+
+<p>Some bundles use properties to configure certain aspects of their behavior. As an example, the default URL for the <tt>cd</tt> command of the shell service can be specified using the property <tt>felix.shell.baseurl</tt>.
+It is a good idea, when implementing bundles, to parameterize them with
+properties where appropriate. To learn about the configuration options
+for specific bundles, refer to the documentation that accompanies them.</p>
+
+<p>Bundle properties are also defined in the <tt>conf/config.properties</tt> property file. Any property placed in this file will be accessible via <tt>BundleContext.getProperty()</tt>
+at run time. The property file uses the standard Java property file
+syntax (i.e., attribute-value pairs). For information on changing the
+default location of this file, refer to the section on <a href="#ApacheFelixFrameworkUsageDocumentation-configuringframework">configuring Felix</a>.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-feedback"></a></p>
+
+<h2><a name="ApacheFelixFrameworkUsageDocumentation-Feedback"></a>Feedback</h2>
+
+<p>Subscribe to the Felix users mailing list by sending a message to <a href="mailto:users-subscribe@felix.apache.org" rel="nofollow">users-subscribe@felix.apache.org</a>; after subscribing, email questions or feedback to <a href="mailto:users@felix.apache.org" rel="nofollow">users@felix.apache.org</a>.</p>
+ </div>
+ </body></html>