Gitiles
Code Review Sign In
gerrit.onosproject.org / onos-felix / c6eda453a494bdf7fb3363a9f7739e8fb25e1dd5 / . / main.distribution / doc / apache-felix-framework-usage-documentation.html
blob: b3b725ca774f8495d70a69aef2458efddad8f4f1 [file] [log] [blame]
Karl Paulsc6eda452010-02-14 22:52:56 +0000[diff] [blame^]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<html><head>
3
4
5
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">
8 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
9 </head><body>
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>
11 <div class="menu">
12<ul>
13 <li><a href="http://felix.apache.org/site/news.html" title="news">news</a></li>
14 <li><a href="http://felix.apache.org/site/license.html" title="license">license</a></li>
15 <li><a href="http://felix.apache.org/site/downloads.cgi" rel="nofollow">downloads</a></li>
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>
18 <li><a href="http://felix.apache.org/site/contributing.html" title="Contributing">contributing</a></li>
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>
22<!-- ApacheCon Ad -->
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>
24<p style="height: 100px;">
25<!-- ApacheCon Ad -->
26</p></li></ul> </div>
27 <div class="main">
28<h1><a name="ApacheFelixFrameworkUsageDocumentation-ApacheFelixFrameworkUsageDocumentation"></a>Apache Felix Framework Usage Documentation</h1>
29
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>
49
50
51<p><a name="ApacheFelixFrameworkUsageDocumentation-downloadingframework"></a></p>
52
53<h2><a name="ApacheFelixFrameworkUsageDocumentation-DownloadingtheFramework"></a>Downloading the Framework</h2>
54
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>
56
57<p><a name="ApacheFelixFrameworkUsageDocumentation-startingframework"></a></p>
58
59<h2><a name="ApacheFelixFrameworkUsageDocumentation-StartingtheFramework"></a>Starting the Framework</h2>
60
61<p>Start the framework from the installation directory by typing:</p>
62
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>
67
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>
74
75<p>If you want to start the framework using a different bundle cache directory, you can do so like this:</p>
76
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>
81
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>
85
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>
93
94<p><a name="ApacheFelixFrameworkUsageDocumentation-frameworkshell"></a></p>
95
96<h2><a name="ApacheFelixFrameworkUsageDocumentation-FrameworkShell"></a>Framework Shell</h2>
97
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>
101
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>
106
107<p><a name="ApacheFelixFrameworkUsageDocumentation-installingbundles"></a></p>
108
109<h3><a name="ApacheFelixFrameworkUsageDocumentation-InstallingBundles"></a>Installing Bundles</h3>
110
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>
117
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>
125
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>
130
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>
135
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>
140
141<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
142<pre>-&gt; install [file:bundle/simple]
143-&gt; ps
144START LEVEL 1
145 ID State Level Name
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)
151-&gt; start 4
152Hello from Bundle 4.
153-&gt;
154</pre>
155</div></div>
156
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>
158
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>
163
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>
169
170<p>For an introduction to writing bundles and services, refer to the Felix bundle tutorial.</p>
171
172<p><a name="ApacheFelixFrameworkUsageDocumentation-installingbundlesproxies"></a></p>
173
174<h3><a name="ApacheFelixFrameworkUsageDocumentation-WebProxyIssueswhenInstallingBundles"></a>Web Proxy Issues when Installing Bundles</h3>
175
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>
180
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>
189
190
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>
192
193<p><a name="ApacheFelixFrameworkUsageDocumentation-autodeploy"></a></p>
194
195<h2><a name="ApacheFelixFrameworkUsageDocumentation-BundleAutoDeploy"></a>Bundle Auto-Deploy</h2>
196
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>
202
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>
207
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>
214
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>
224
225
226<p>The next section describes how to set and use configuration properties.</p>
227
228<p><a name="ApacheFelixFrameworkUsageDocumentation-configuringframework"></a></p>
229
230<h2><a name="ApacheFelixFrameworkUsageDocumentation-ConfiguringtheFramework"></a>Configuring the Framework</h2>
231
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>
239
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>
246
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>
248
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>
269
270
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>
272
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>
327
328
329<p>The Felix framework installation contains a default <tt>conf/config.properties</tt> file for automatically starting the shell-related bundles.</p>
330
331<p><a name="ApacheFelixFrameworkUsageDocumentation-migrating"></a></p>
332
333<h3><a name="ApacheFelixFrameworkUsageDocumentation-MigratingfromEarlierVersions"></a>Migrating from Earlier Versions</h3>
334
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>
336
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>
361
362
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>
366
367<p><a name="ApacheFelixFrameworkUsageDocumentation-propertysubstitution"></a></p>
368
369<h3><a name="ApacheFelixFrameworkUsageDocumentation-SystemPropertySubstituion"></a>System Property Substituion</h3>
370
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>
378
379<p><a name="ApacheFelixFrameworkUsageDocumentation-configuringbundles"></a></p>
380
381<h2><a name="ApacheFelixFrameworkUsageDocumentation-ConfiguringBundles"></a>Configuring Bundles</h2>
382
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>
387
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>
392
393<p><a name="ApacheFelixFrameworkUsageDocumentation-feedback"></a></p>
394
395<h2><a name="ApacheFelixFrameworkUsageDocumentation-Feedback"></a>Feedback</h2>
396
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>
398 </div>
399 </body></html>