Gitiles
Code Review Sign In
gerrit.onosproject.org / onos-felix / a06694ccb5c15792bc0ddf674febd38b915e6461 / . / main / doc / apache-felix-framework-usage-documentation.html
blob: b3b725ca774f8495d70a69aef2458efddad8f4f1 [file] [log] [blame]
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]2<html><head>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]3
4
5
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]6 <title>Apache Felix - Apache Felix Framework Usage Documentation</title>
7 <link rel="stylesheet" href="apache-felix-framework-usage-documentation_files/site.css" type="text/css" media="all">
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]8 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
9 </head><body>
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]10 <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>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]11 <div class="menu">
Karl Pauls4994cb02008-12-20 17:15:21 +0000[diff] [blame]12<ul>
Karl Pauls44987e52007-09-16 20:54:55 +0000[diff] [blame]13 <li><a href="http://felix.apache.org/site/news.html" title="news">news</a></li>
Karl Pauls44987e52007-09-16 20:54:55 +0000[diff] [blame]14 <li><a href="http://felix.apache.org/site/license.html" title="license">license</a></li>
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]15 <li><a href="http://felix.apache.org/site/downloads.cgi" rel="nofollow">downloads</a></li>
Karl Pauls44987e52007-09-16 20:54:55 +0000[diff] [blame]16 <li><a href="http://felix.apache.org/site/documentation.html" title="documentation">documentation</a></li>
17 <li><a href="http://felix.apache.org/site/mailinglists.html" title="mailinglists">mailing lists</a></li>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]18 <li><a href="http://felix.apache.org/site/contributing.html" title="Contributing">contributing</a></li>
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]19 <li><a href="http://www.apache.org/" rel="nofollow">asf</a></li>
20 <li><a href="http://www.apache.org/foundation/sponsorship.html" rel="nofollow">sponsorship</a></li>
21 <li><a href="http://www.apache.org/foundation/thanks.html" rel="nofollow">sponsors</a>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]22<!-- ApacheCon Ad -->
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]23<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>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]24<p style="height: 100px;">
25<!-- ApacheCon Ad -->
Karl Pauls4994cb02008-12-20 17:15:21 +0000[diff] [blame]26</p></li></ul> </div>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]27 <div class="main">
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]28<h1><a name="ApacheFelixFrameworkUsageDocumentation-ApacheFelixFrameworkUsageDocumentation"></a>Apache Felix Framework Usage Documentation</h1>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]29
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]30<ul>
31 <li><a href="#ApacheFelixFrameworkUsageDocumentation-downloadingframework">Downloading the Framework</a></li>
32 <li><a href="#ApacheFelixFrameworkUsageDocumentation-startingframework">Starting the Framework</a></li>
33 <li><a href="#ApacheFelixFrameworkUsageDocumentation-frameworkshell">Framework Shell</a>
34 <ul>
35 <li><a href="#ApacheFelixFrameworkUsageDocumentation-installingbundles">Installing Bundles</a></li>
36 <li><a href="#ApacheFelixFrameworkUsageDocumentation-installingbundlesproxies">Web Proxy Issues when Installing Bundles</a></li>
37 </ul>
38 </li>
39 <li><a href="#ApacheFelixFrameworkUsageDocumentation-autodeploy">Bundle Auto-Deploy</a></li>
40 <li><a href="#ApacheFelixFrameworkUsageDocumentation-configuringframework">Configuring the Framework</a>
41 <ul>
42 <li><a href="#ApacheFelixFrameworkUsageDocumentation-migrating">Migrating from Earlier Versions</a></li>
43 <li><a href="#ApacheFelixFrameworkUsageDocumentation-propertysubstitution">System Property Substitution</a></li>
44 </ul>
45 </li>
46 <li><a href="#ApacheFelixFrameworkUsageDocumentation-configuringbundles">Configuring Bundles</a></li>
47 <li><a href="#ApacheFelixFrameworkUsageDocumentation-feedback">Feedback</a></li>
48</ul>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]49
50
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]51<p><a name="ApacheFelixFrameworkUsageDocumentation-downloadingframework"></a></p>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]52
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]53<h2><a name="ApacheFelixFrameworkUsageDocumentation-DownloadingtheFramework"></a>Downloading the Framework</h2>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]54
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]55<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>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]56
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]57<p><a name="ApacheFelixFrameworkUsageDocumentation-startingframework"></a></p>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]58
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]59<h2><a name="ApacheFelixFrameworkUsageDocumentation-StartingtheFramework"></a>Starting the Framework</h2>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]60
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]61<p>Start the framework from the installation directory by typing:</p>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]62
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]63<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
64<pre>java -jar bin/felix.jar
65</pre>
66</div></div>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]67
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]68<p>The framework launcher starts the framework and installs a bundles contained in the <tt>bundle</tt>
69directory of the current directory. By default, the bundle directory
70contains a simple text-based shell to interact with the framework.
71Bundles installed into the framework are copied into a bundle cache
72directory for subsequent executions. By default, the framework creates
73a 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>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]74
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]75<p>If you want to start the framework using a different bundle cache directory, you can do so like this:</p>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]76
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]77<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
78<pre>java -jar bin/felix.jar &lt;cache-path&gt;
79</pre>
80</div></div>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]81
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]82<p>Where <tt>&lt;cache-path&gt;</tt> is the path you want to use as the
83bundle cache. If you specify a relative cache path, then it will be
84treated as relative to the current working directory.</p>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]85
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]86<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
87versions of the framework prompted for a profile name when executed.
88The profile name was used to create a directory inside <tt>.felix/</tt>
89in the user home directory. This approach allowed users to have
90different sets of bundles for different purposes, e.g., testing,
91production, etc. If this behavior is still desired, it is very easy to
92mimic. 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>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]93
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]94<p><a name="ApacheFelixFrameworkUsageDocumentation-frameworkshell"></a></p>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]95
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]96<h2><a name="ApacheFelixFrameworkUsageDocumentation-FrameworkShell"></a>Framework Shell</h2>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]97
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]98<p>The main way to interact with the framework is via its shell. Felix'
99shell is implemented as an OSGi service that, be default, uses a simple
100text-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 &lt;command-name&gt;</tt> to get help for a specific command.</p>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]101
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]102<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>
103to stop the System Bundle; any installed bundles will automatically be
104reloaded (and potentially restarted) the next time you launch with the
105associated cache.</p>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]106
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]107<p><a name="ApacheFelixFrameworkUsageDocumentation-installingbundles"></a></p>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]108
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]109<h3><a name="ApacheFelixFrameworkUsageDocumentation-InstallingBundles"></a>Installing Bundles</h3>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]110
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]111<p>A bundle is the OSGi term for a component for the OSGi framework. A
112bundle is simply a JAR file containing a manifest and some combination
113of Java classes, embedded JAR files, native code, and resources. A
114bundle may provide some specific functionality for the user or it may
115implement a service that other bundles can use; bundles can only use
116functionality from other bundles through shared services and packages.</p>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]117
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]118<p>The Felix framework is packaged with three bundles, which are located in the <tt>bundle/</tt>
119directory of the framework installation directory. There are bundles
120for the Felix shell service, a text-based shell service user interface,
121and a bundle repository service. In addition to these bundles, the
122bundle repository services provides access to other bundles for easy
123installation. The bundle repository service provides a shell command,
124named <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>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]125
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]126<p>Before installing any bundles, it is important to understand how
127bundles are manually deployed into the framework. Bundles are deployed
128in two stages; first they are installed, then they are started. To
129install 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>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]130
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]131<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
132<pre>install file:/path/to/bundle/bundle.jar
133</pre>
134</div></div>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]135
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]136<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>
137shell command is used to list all installed bundles and to obtain the
138bundle's identifier. The following Felix shell session capture
139illustrates how to start the <tt>bundle.jar</tt> bundle:</p>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]140
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]141<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
142<pre>-&gt; install [file:bundle/simple]
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]143-&gt; ps
144START LEVEL 1
145 ID State Level Name
Karl Pauls44c941b2009-09-06 22:21:18 +0000[diff] [blame]146[ 0] [Active ] [ 0] System Bundle (2.0.0)
147[ 1] [Active ] [ 1] Shell Service (1.4.0)
148[ 2] [Active ] [ 1] Shell TUI (1.4.0)
149[ 3] [Active ] [ 1] Bundle Repository (1.4.0)
150[ 4] [Installed ] [ 1] Bundle Example (1.0.0)
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]151-&gt; start 4
Karl Pauls44c941b2009-09-06 22:21:18 +0000[diff] [blame]152Hello from Bundle 4.
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]153-&gt;
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]154</pre>
155</div></div>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]156
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]157<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>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]158
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]159<p>Bundles can be updated using the <tt>update</tt> command. The update
160command allows you to specify an URL from which to retrieve the updated
161bundle, but if one is not specified it will try to update the bundle
162from the bundle's <tt>Bundle-UpdateLocation</tt> manifest attribute, if present, or the bundle's original location URL.</p>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]163
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]164<p><b>Important:</b> When you <tt>update</tt> or <tt>uninstall</tt> a
165bundle, the changes appear to take effect immediately, but in reality
166the changes are only partially enacted. If a bundle is updated or
167uninstalled and it was exporting packages, these packages are not
168removed 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>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]169
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]170<p>For an introduction to writing bundles and services, refer to the Felix bundle tutorial.</p>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]171
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]172<p><a name="ApacheFelixFrameworkUsageDocumentation-installingbundlesproxies"></a></p>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]173
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]174<h3><a name="ApacheFelixFrameworkUsageDocumentation-WebProxyIssueswhenInstallingBundles"></a>Web Proxy Issues when Installing Bundles</h3>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]175
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]176<p>If you use a proxy for Web access, then you may run into difficulty
177using the Felix shell to install bundles from a remote URL. To remedy
178this situation, certain system properties must be set to make Felix
179work with your proxy. These properties are:</p>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]180
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]181<ul>
182 <li><tt>http.proxyHost</tt> - the name of the proxy host.</li>
183 <li><tt>http.proxyPort</tt> - the port of the proxy host.</li>
184 <li><tt>http.proxyAuth</tt>
185- the user name and password to use when connecting to the proxy; this
186string should be the user name and password separated by a colon (e.g.,
187<tt>rickhall:mypassword</tt>).</li>
188</ul>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]189
190
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]191<p>These system properties can be set directly on the command line when starting the JVM using the standard "<tt>-D&lt;prop&gt;=&lt;value&gt;</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>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]192
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]193<p><a name="ApacheFelixFrameworkUsageDocumentation-autodeploy"></a></p>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]194
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]195<h2><a name="ApacheFelixFrameworkUsageDocumentation-BundleAutoDeploy"></a>Bundle Auto-Deploy</h2>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]196
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]197<p>To minimize the amount of configuration necessary to install bundles
198when you launch the framework, the Felix launcher uses the concept of
199an "auto-deploy" directory. The Felix launcher deploys all bundles in
200the auto-deploy directory into the framework instance during startup.
201By 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>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]202
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]203<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
204<pre>java -jar bin/felix.jar -b /path/to/dir
205</pre>
206</div></div>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]207
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]208<p>Specifying an auto-deploy directory replaces the default directory,
209it does not augment it. The default deployment actions performed on the
210bundles in the auto-deploy directory are: install, update, and start.
211Both the location of the auto-deploy directory and the deployment
212actions performed can be controlled by the following configuration
213properties, respectively:</p>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]214
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]215<ul>
216 <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>
217 <li><tt>felix.auto.deploy.action</tt>
218- Specifies the auto-deploy actions to be found on bundle JAR files
219found in the auto-deploy directory. The possible actions are <tt>install</tt>, <tt>update</tt>, <tt>start</tt>, and <tt>uninstall</tt>.
220If no actions are specified, then the auto-deploy directory is not
221processed. There is no default value for this property, but the default
222<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>
223</ul>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]224
225
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]226<p>The next section describes how to set and use configuration properties.</p>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]227
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]228<p><a name="ApacheFelixFrameworkUsageDocumentation-configuringframework"></a></p>
Karl Pauls44c941b2009-09-06 22:21:18 +0000[diff] [blame]229
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]230<h2><a name="ApacheFelixFrameworkUsageDocumentation-ConfiguringtheFramework"></a>Configuring the Framework</h2>
Karl Pauls44c941b2009-09-06 22:21:18 +0000[diff] [blame]231
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]232<p>Both the Felix framework and the launcher use configuration
233properties to alter their default behavior. The framework can only be
234configured by passing properties into its constructor, but the launcher
235provides a mechanism to configure the framework via a property file.
236The launcher The Felix framework uses properties to configure certain
237aspects of its behavior. The framework launcher reads configuration
238properties from <tt>conf/config.properties</tt>. This file uses standard Java property file syntax.</p>
Karl Pauls44c941b2009-09-06 22:21:18 +0000[diff] [blame]239
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]240<p>The launcher also supports setting system properties via the <tt>conf/system.properties</tt>
241file. This file is purely for convenience when you need to repeatedly
242set system properties when running the framework. While the framework
243itself does not look at system properties, the launcher does copy any
244framework configuration properties found in the system properties into
245the framework configuration map, also for your convenience.</p>
Karl Pauls44c941b2009-09-06 22:21:18 +0000[diff] [blame]246
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]247<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>
Karl Pauls44c941b2009-09-06 22:21:18 +0000[diff] [blame]248
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]249<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
250<pre>java -Dfelix.config.properties=file:/home/rickhall/config.properties -jar bin/felix.jar
251</pre>
252</div></div>
253
254<p>Configuration and system properties are accessible at run time via <tt>BundleContext.getProperty()</tt>, but configuration properties override system properties.</p>
255
256<p>The following configuration properties are specifically for the launcher:</p>
257
258<ul>
259 <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>
260 <li><tt>felix.auto.deploy.action</tt>
261- Specifies the auto-deploy actions to be found on bundle JAR files
262found 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>
263 <li><tt>felix.auto.install.&lt;n&gt;</tt> - Space-delimited list of bundle URLs to automatically install when Felix is started, where <tt>&lt;n&gt;</tt> is the start level into which the bundle will be installed (e.g., <tt>felix.auto.install.2</tt>).</li>
264 <li><tt>felix.auto.start.&lt;n&gt;</tt> - Space-delimited list of bundle URLs to automatically install and start when Felix is started, where <tt>&lt;n&gt;</tt> is the start level into which the bundle will be installed (e.g., <tt>felix.auto.start.2</tt>).</li>
265 <li><tt>felix.shutdown.hook</tt>
266- Specifies whether the launcher should install a shutdown hook to
267cleanly shutdown the framework on process exit. The default value is <tt>true</tt>.</li>
268</ul>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]269
270
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]271<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>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]272
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]273<ul>
274 <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>
275in the current working directory. The value should be a valid directory
276name. The directory name can be either absolute or relative. Relative
277directory names are relative to the current working directory. The
278specified directory will be created if it does not exist.</li>
279 <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>
280is set to a relative name, by default it is relative to the current
281working directory. If this property is set, then it will be calculated
282as being relative to the specified root directory.</li>
283 <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>
284 <li><tt>felix.cache.bufsize</tt>
285- Sets the buffer size to be used by the cache; the default value is
2864096. The integer value of this string provides control over the size
287of the internal buffer of the disk cache for performance reasons.</li>
288 <li><tt>org.osgi.framework.system.packages</tt>
289- Specifies a comma-delimited list of packages that should be exported
290via the System Bundle from the parent class loader. The framework will
291set this to a reasonable default. If the value is specified, it
292replaces any default value.</li>
293 <li><tt>org.osgi.framework.system.packages.extra</tt>
294- Specifies a comma-delimited list of packages that should be exported
295via the System Bundle from the parent class loader in addition to the
296packages 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>
297 <li><tt>org.osgi.framework.bootdelegation</tt>
298- Specifies a comma-delimited list of packages that should be made
299implicitly available to all bundles from the parent class loader. It is
300recommended not to use this property since it breaks modularity. The
301default value is empty.</li>
302 <li><tt>felix.bootdelegation.implicit</tt>
303- Specifies whether the framework should try to guess when to
304implicitly boot delegate to ease integration with external code. The
305default value is <tt>true</tt>.</li>
306 <li><tt>felix.systembundle.activators</tt> - A <tt>List</tt> of <tt>BundleActivator</tt>
307instances that are started/stopped when the System Bundle is
308started/stopped. The specified instances will receive the System
309Bundle's <tt>BundleContext</tt> when invoked. (This property cannot be
310set in the configuration file since it requires instances; it can only
311be passed into Felix' constructor directly.)</li>
312 <li><tt>felix.log.logger</tt> - An instance of <tt>Logger</tt>
313that the framework uses as its default logger. (This property cannot be
314set in the configuration file since it requires an instance; it can
315only be passed into Felix' constructor directly.)</li>
316 <li><tt>felix.log.level</tt>
317- An integer value indicating the degree of logging reported by the
318framework; the higher the value the more logging is reported. If zero
319('0') is specified, then logging is turned off completely. The log
320levels match those specified in the OSGi Log Service (i.e., 1 = error,
3212 = warning, 3 = information, and 4 = debug). The default value is 1.</li>
322 <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>
323 <li><tt>felix.startlevel.bundle</tt> - The default start level for newly installed bundles; the default value is 1.</li>
324 <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>
325 <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>
326</ul>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]327
328
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]329<p>The Felix framework installation contains a default <tt>conf/config.properties</tt> file for automatically starting the shell-related bundles.</p>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]330
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]331<p><a name="ApacheFelixFrameworkUsageDocumentation-migrating"></a></p>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]332
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]333<h3><a name="ApacheFelixFrameworkUsageDocumentation-MigratingfromEarlierVersions"></a>Migrating from Earlier Versions</h3>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]334
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]335<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>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]336
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]337<ul>
338 <li><b>Removed</b>
339 <ul>
340 <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>
341 <li><tt>felix.strict.osgi</tt> - No longer needed, since all non-specification features have been removed.</li>
342 <li><tt>felix.cache.dir</tt> - No longer needed, since Felix no longer uses bundle cache profiles for saving sets of bundles.</li>
343 <li><tt>felix.cache.profile</tt> - No longer needed, since Felix no longer uses bundle cache profiles for saving sets of bundles.</li>
344 </ul>
345 </li>
346 <li><b>Renamed</b>
347 <ul>
348 <li><tt>felix.cache.profiledir</tt> - The equivalent of this property is now named <tt>org.osgi.framework.storage</tt>.</li>
349 <li><tt>felix.startlevel.framework</tt> - The equivalent of this property is now named <tt>org.osgi.framework.startlevel.beginning</tt>.</li>
350 </ul>
351 </li>
352 <li><b>Introduced</b>
353 <ul>
354 <li><tt>org.osgi.framework.system.packages.extra</tt> - New property, as described above, added to align with standard framework API.</li>
355 <li><tt>org.osgi.framework.storage.clean</tt> - New property, as described above, added to align with standard framework API.</li>
356 <li><tt>felix.cache.rootdir</tt> - Introduced as a result of removing bundle profiles to help resolve relative bundle cache directories.</li>
357 <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>
358 </ul>
359 </li>
360</ul>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]361
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]362
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]363<p>For the most part, these changes are minor and previous behavior
364achieved from older configuration properties is either easily attained
365with the new properties or no longer necessary.</p>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]366
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]367<p><a name="ApacheFelixFrameworkUsageDocumentation-propertysubstitution"></a></p>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]368
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]369<h3><a name="ApacheFelixFrameworkUsageDocumentation-SystemPropertySubstituion"></a>System Property Substituion</h3>
Karl Pauls44c941b2009-09-06 22:21:18 +0000[diff] [blame]370
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]371<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>${&lt;property&gt;</tt>} syntax, where <tt>&lt;property&gt;</tt>
372is the name of a system property to substitute. When such a property
373value is retrieved by a bundle, the system property value will be
374substituted into the bundle property value as appropriate. It is
375possible to have nested system property substitution, in which case the
376inner-most property is substituted first, then the next inner most,
377until reaching the outer most.</p>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]378
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]379<p><a name="ApacheFelixFrameworkUsageDocumentation-configuringbundles"></a></p>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]380
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]381<h2><a name="ApacheFelixFrameworkUsageDocumentation-ConfiguringBundles"></a>Configuring Bundles</h2>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]382
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]383<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>.
384It is a good idea, when implementing bundles, to parameterize them with
385properties where appropriate. To learn about the configuration options
386for specific bundles, refer to the documentation that accompanies them.</p>
Karl Paulsf7d389c2008-11-06 16:22:54 +0000[diff] [blame]387
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]388<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>
389at run time. The property file uses the standard Java property file
390syntax (i.e., attribute-value pairs). For information on changing the
391default location of this file, refer to the section on <a href="#ApacheFelixFrameworkUsageDocumentation-configuringframework">configuring Felix</a>.</p>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]392
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]393<p><a name="ApacheFelixFrameworkUsageDocumentation-feedback"></a></p>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]394
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]395<h2><a name="ApacheFelixFrameworkUsageDocumentation-Feedback"></a>Feedback</h2>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]396
Karl Pauls93f7ea22009-10-11 20:18:06 +0000[diff] [blame]397<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>
Richard S. Hall2cd5bed2007-07-16 20:32:41 +0000[diff] [blame]398 </div>
Karl Pauls44c941b2009-09-06 22:21:18 +0000[diff] [blame]399 </body></html>