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