| Karl Pauls | 7847043 | 2010-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> |
| 69 | directory of the current directory. By default, the bundle directory |
| 70 | contains a simple text-based shell to interact with the framework. |
| 71 | Bundles installed into the framework are copied into a bundle cache |
| 72 | directory for subsequent executions. By default, the framework creates |
| 73 | a cache directory, called <tt>felix-cache</tt>, in your current working directory; this behavior is configurable, see the <a href="http://felix.apache.org/site/apache-felix-framework-bundle-cache.html" title="Apache Felix Framework Bundle Cache">Apache Felix Framework Bundle Cache</a> document for more details.</p> |
| 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 <cache-path> |
| 79 | </pre> |
| 80 | </div></div> |
| 81 | |
| 82 | <p>Where <tt><cache-path></tt> is the path you want to use as the |
| 83 | bundle cache. If you specify a relative cache path, then it will be |
| 84 | treated 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 |
| 87 | versions of the framework prompted for a profile name when executed. |
| 88 | The profile name was used to create a directory inside <tt>.felix/</tt> |
| 89 | in the user home directory. This approach allowed users to have |
| 90 | different sets of bundles for different purposes, e.g., testing, |
| 91 | production, etc. If this behavior is still desired, it is very easy to |
| 92 | mimic. Modify <tt>conf/config.properties</tt> to include "<tt>felix.cache.rootdir=${user.home}/.felix</tt>". Now, if you start Felix with something like "<tt>java -jar bin/felix.jar foo</tt>", it will use "<tt>${user.home}/.felix/foo/</tt>" as the bundle cache directory, where "<tt>${user.home</tt>}" is automatically substituted with the appropriate system property by the launcher.</p></td></tr></tbody></table></div> |
| 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' |
| 99 | shell is implemented as an OSGi service that, be default, uses a simple |
| 100 | text-based user interface. After starting the framework, type <tt>help</tt> into the shell to see the list of the available commands and <tt>help <command-name></tt> to get help for a specific command.</p> |
| 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> |
| 103 | to stop the System Bundle; any installed bundles will automatically be |
| 104 | reloaded (and potentially restarted) the next time you launch with the |
| 105 | associated 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 |
| 112 | bundle is simply a JAR file containing a manifest and some combination |
| 113 | of Java classes, embedded JAR files, native code, and resources. A |
| 114 | bundle may provide some specific functionality for the user or it may |
| 115 | implement a service that other bundles can use; bundles can only use |
| 116 | functionality 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> |
| 119 | directory of the framework installation directory. There are bundles |
| 120 | for the Felix shell service, a text-based shell service user interface, |
| 121 | and a bundle repository service. In addition to these bundles, the |
| 122 | bundle repository services provides access to other bundles for easy |
| 123 | installation. The bundle repository service provides a shell command, |
| 124 | named <tt>obr</tt>, to access available bundles; refer to the <a href="http://felix.apache.org/site/apache-felix-osgi-bundle-repository.html" title="Apache Felix OSGi Bundle Repository">Apache Felix OSGi Bundle Repository</a> for more information.</p> |
| 125 | |
| 126 | <p>Before installing any bundles, it is important to understand how |
| 127 | bundles are manually deployed into the framework. Bundles are deployed |
| 128 | in two stages; first they are installed, then they are started. To |
| 129 | install a bundle use the <tt>install</tt> shell command followed by a bundle URL. For example, to install a <tt>bundle.jar</tt> bundle you type (assuming you have started Felix from its installation directory):</p> |
| 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> |
| 137 | shell command is used to list all installed bundles and to obtain the |
| 138 | bundle's identifier. The following Felix shell session capture |
| 139 | illustrates 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>-> install [file:bundle/simple] |
| 143 | -> ps |
| 144 | START 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 | -> start 4 |
| 152 | Hello from Bundle 4. |
| 153 | -> |
| 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 |
| 160 | command allows you to specify an URL from which to retrieve the updated |
| 161 | bundle, but if one is not specified it will try to update the bundle |
| 162 | from 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 |
| 165 | bundle, the changes appear to take effect immediately, but in reality |
| 166 | the changes are only partially enacted. If a bundle is updated or |
| 167 | uninstalled and it was exporting packages, these packages are not |
| 168 | removed until the framework is refreshed using the <tt>PackageAdmin</tt> service. The Felix shell offers a convenient <tt>refresh</tt> command for this purpose.</p> |
| 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 |
| 177 | using the Felix shell to install bundles from a remote URL. To remedy |
| 178 | this situation, certain system properties must be set to make Felix |
| 179 | work 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 |
| 186 | string 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<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> |
| 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 |
| 198 | when you launch the framework, the Felix launcher uses the concept of |
| 199 | an "auto-deploy" directory. The Felix launcher deploys all bundles in |
| 200 | the auto-deploy directory into the framework instance during startup. |
| 201 | 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> |
| 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, |
| 209 | it does not augment it. The default deployment actions performed on the |
| 210 | bundles in the auto-deploy directory are: install, update, and start. |
| 211 | Both the location of the auto-deploy directory and the deployment |
| 212 | actions performed can be controlled by the following configuration |
| 213 | properties, 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 |
| 219 | found in the auto-deploy directory. The possible actions are <tt>install</tt>, <tt>update</tt>, <tt>start</tt>, and <tt>uninstall</tt>. |
| 220 | If no actions are specified, then the auto-deploy directory is not |
| 221 | processed. 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 |
| 233 | properties to alter their default behavior. The framework can only be |
| 234 | configured by passing properties into its constructor, but the launcher |
| 235 | provides a mechanism to configure the framework via a property file. |
| 236 | The launcher The Felix framework uses properties to configure certain |
| 237 | aspects of its behavior. The framework launcher reads configuration |
| 238 | properties 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> |
| 241 | file. This file is purely for convenience when you need to repeatedly |
| 242 | set system properties when running the framework. While the framework |
| 243 | itself does not look at system properties, the launcher does copy any |
| 244 | framework configuration properties found in the system properties into |
| 245 | the 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 |
| 262 | 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> |
| 263 | <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> |
| 264 | <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> |
| 265 | <li><tt>felix.shutdown.hook</tt> |
| 266 | - Specifies whether the launcher should install a shutdown hook to |
| 267 | cleanly 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> |
| 275 | in the current working directory. The value should be a valid directory |
| 276 | name. The directory name can be either absolute or relative. Relative |
| 277 | directory names are relative to the current working directory. The |
| 278 | specified 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> |
| 280 | is set to a relative name, by default it is relative to the current |
| 281 | working directory. If this property is set, then it will be calculated |
| 282 | as 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 |
| 286 | 4096. The integer value of this string provides control over the size |
| 287 | of 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 |
| 290 | via the System Bundle from the parent class loader. The framework will |
| 291 | set this to a reasonable default. If the value is specified, it |
| 292 | replaces 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 |
| 295 | via the System Bundle from the parent class loader in addition to the |
| 296 | 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> |
| 297 | <li><tt>org.osgi.framework.bootdelegation</tt> |
| 298 | - Specifies a comma-delimited list of packages that should be made |
| 299 | implicitly available to all bundles from the parent class loader. It is |
| 300 | recommended not to use this property since it breaks modularity. The |
| 301 | default value is empty.</li> |
| 302 | <li><tt>felix.bootdelegation.implicit</tt> |
| 303 | - Specifies whether the framework should try to guess when to |
| 304 | implicitly boot delegate to ease integration with external code. The |
| 305 | default value is <tt>true</tt>.</li> |
| 306 | <li><tt>felix.systembundle.activators</tt> - A <tt>List</tt> of <tt>BundleActivator</tt> |
| 307 | instances that are started/stopped when the System Bundle is |
| 308 | started/stopped. The specified instances will receive the System |
| 309 | Bundle's <tt>BundleContext</tt> when invoked. (This property cannot be |
| 310 | set in the configuration file since it requires instances; it can only |
| 311 | be passed into Felix' constructor directly.)</li> |
| 312 | <li><tt>felix.log.logger</tt> - An instance of <tt>Logger</tt> |
| 313 | that the framework uses as its default logger. (This property cannot be |
| 314 | set in the configuration file since it requires an instance; it can |
| 315 | only 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 |
| 318 | framework; the higher the value the more logging is reported. If zero |
| 319 | ('0') is specified, then logging is turned off completely. The log |
| 320 | levels match those specified in the OSGi Log Service (i.e., 1 = error, |
| 321 | 2 = 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 |
| 364 | achieved from older configuration properties is either easily attained |
| 365 | with 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>${<property></tt>} syntax, where <tt><property></tt> |
| 372 | is the name of a system property to substitute. When such a property |
| 373 | value is retrieved by a bundle, the system property value will be |
| 374 | substituted into the bundle property value as appropriate. It is |
| 375 | possible to have nested system property substitution, in which case the |
| 376 | inner-most property is substituted first, then the next inner most, |
| 377 | 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 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>. |
| 384 | It is a good idea, when implementing bundles, to parameterize them with |
| 385 | properties where appropriate. To learn about the configuration options |
| 386 | for 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> |
| 389 | at run time. The property file uses the standard Java property file |
| 390 | syntax (i.e., attribute-value pairs). For information on changing the |
| 391 | default 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> |