| Karl Pauls | bbc2957 | 2010-12-26 21:07: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"> |
| 2 | <html><head> |
| 3 | |
| 4 | |
| 5 | |
| 6 | <title>Apache Felix - Apache Felix Framework Configuration Properties</title> |
| 7 | <link rel="stylesheet" href="apache-felix-framework-configuration-properties_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-configuration-properties_files/logo.png" border="0"></a></div><div class="header"><a href="http://www.apache.org/"><img alt="Apache" src="apache-felix-framework-configuration-properties_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-configuration-properties_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="ApacheFelixFrameworkConfigurationProperties-ApacheFelixFrameworkConfigurationProperties"></a>Apache Felix Framework Configuration Properties</h1> |
| 30 | |
| 31 | <ul> |
| 32 | <li><a href="#ApacheFelixFrameworkConfigurationProperties-overview">Overview</a></li> |
| 33 | <li><a href="#ApacheFelixFrameworkConfigurationProperties-framework">Framework configuration properties</a></li> |
| 34 | <li><a href="#ApacheFelixFrameworkConfigurationProperties-launcher">Launcher configuration properties</a></li> |
| 35 | <li><a href="#ApacheFelixFrameworkConfigurationProperties-migrating">Mirgrating from earlier versions</a></li> |
| 36 | <li><a href="#ApacheFelixFrameworkConfigurationProperties-feedback">Feedback</a></li> |
| 37 | </ul> |
| 38 | |
| 39 | |
| 40 | <p><a name="ApacheFelixFrameworkConfigurationProperties-overview"></a></p> |
| 41 | |
| 42 | <h2><a name="ApacheFelixFrameworkConfigurationProperties-Overview"></a>Overview</h2> |
| 43 | |
| 44 | <p>This document describes the various configuration properties related |
| 45 | to the Apache Felix Framework. Technically, there are framework |
| 46 | properties and launcher properties. If you are using the Felix |
| 47 | Framework JAR file (i.e., <tt>org.apache.felix.framework-x.y.x.jar</tt>), then you can only use framework properties. On the other hand, if you are using the Felix Main launcher JAR (i.e., <tt>felix.jar</tt> or <tt>org.apache.felix.main-x.y.z.jar</tt>), then you can use both framework and launcher properties. This document will describe both sets of properties.</p> |
| 48 | |
| 49 | <p>Note that the framework does not use system properties to find its |
| 50 | configuration properties, it only consults the map passed into its |
| 51 | constructor. In contrast to bundles, which use <tt>BundleContext.getProperty()</tt>, |
| 52 | which exposes both configuration and system properties at execution |
| 53 | time. In the case of overlap, the configuration properties override |
| 54 | system properties. As a convenience, if you are using the Felix |
| 55 | launcher, it will copy all configuration properties it finds in the |
| 56 | system properties to the configuration map passed into the framework |
| 57 | constructor, which allows you to set configuration properties on the |
| 58 | command line. This feature is <b>not</b> available if you are just using the Felix framework JAR file.</p> |
| 59 | |
| 60 | <p><a name="ApacheFelixFrameworkConfigurationProperties-framework"></a></p> |
| 61 | |
| 62 | <h2><a name="ApacheFelixFrameworkConfigurationProperties-Frameworkconfigurationproperties"></a>Framework configuration properties</h2> |
| 63 | |
| 64 | <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> |
| 65 | |
| 66 | <ul> |
| 67 | <li><tt>org.osgi.framework.executionenvironment</tt> - Sets the |
| 68 | OSGi execution environment for the framework. The framework tries to |
| 69 | set this to a reasonable default value. If you specify a value, it |
| 70 | overrides the framework default. Refer to the OSGi specification for |
| 71 | appropriate execution environment values.</li> |
| 72 | <li><tt>org.osgi.framework.storage</tt> - Sets the directory to use as the bundle cache; by default the bundle cache directory is <tt>felix-cache</tt> |
| 73 | in the current working directory. The value should be a valid directory |
| 74 | name. The directory name can be either absolute or relative. Relative |
| 75 | directory names are relative to the current working directory. The |
| 76 | specified directory will be created if it does not exist.</li> |
| 77 | <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> |
| 78 | is set to a relative name, by default it is relative to the current |
| 79 | working directory. If this property is set, then it will be calculated |
| 80 | as being relative to the specified root directory.</li> |
| 81 | <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> |
| 82 | <li><tt>felix.cache.locking</tt> |
| 83 | - Enables or disables bundle cache locking, which is used to prevent |
| 84 | concurrent access to the bundle cache. This is enabled by default, but |
| 85 | on older/smaller JVMs file channel locking is not available; set this |
| 86 | property to <tt>false</tt> to disable it.</li> |
| 87 | <li><tt>felix.cache.bufsize</tt> |
| 88 | - Sets the buffer size to be used by the cache; the default value is |
| 89 | 4096. The integer value of this string provides control over the size |
| 90 | of the internal buffer of the disk cache for performance reasons.</li> |
| 91 | <li><tt>org.osgi.framework.system.packages</tt> |
| 92 | - Specifies a comma-delimited list of packages that should be exported |
| 93 | via the System Bundle from the framework class loader. The framework |
| 94 | will set this to a reasonable default. If the value is specified, it |
| 95 | replaces any default value.</li> |
| 96 | <li><tt>org.osgi.framework.system.packages.extra</tt> |
| 97 | - Specifies a comma-delimited list of packages that should be exported |
| 98 | via the System Bundle from the framework class loader in addition to |
| 99 | 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> |
| 100 | <li><tt>org.osgi.framework.bootdelegation</tt> |
| 101 | - Specifies a comma-delimited list of packages that should be made |
| 102 | implicitly available to all bundles from the parent class loader. It is |
| 103 | recommended not to use this property since it breaks modularity. The |
| 104 | default value is empty.</li> |
| 105 | <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> |
| 106 | <li><tt>felix.bootdelegation.implicit</tt> |
| 107 | - Specifies whether the framework should try to guess when to |
| 108 | implicitly boot delegate to ease integration with external code. The |
| 109 | default value is <tt>true</tt>.</li> |
| 110 | <li><tt>felix.systembundle.activators</tt> - A <tt>List</tt> of <tt>BundleActivator</tt> |
| 111 | instances that are started/stopped when the System Bundle is |
| 112 | started/stopped. The specified instances will receive the System |
| 113 | Bundle's <tt>BundleContext</tt> when invoked. (This property cannot be |
| 114 | set in the configuration file since it requires instances; it can only |
| 115 | be passed into Felix' constructor directly.)</li> |
| 116 | <li><tt>felix.log.logger</tt> - An instance of <tt>Logger</tt> |
| 117 | that the framework uses as its default logger. (This property cannot be |
| 118 | set in the configuration file since it requires an instance; it can |
| 119 | only be passed into Felix' constructor directly.)</li> |
| 120 | <li><tt>felix.log.level</tt> |
| 121 | - An integer value indicating the degree of logging reported by the |
| 122 | framework; the higher the value the more logging is reported. If zero |
| 123 | ('0') is specified, then logging is turned off completely. The log |
| 124 | levels match those specified in the OSGi Log Service (i.e., 1 = error, |
| 125 | 2 = warning, 3 = information, and 4 = debug). The default value is 1.</li> |
| 126 | <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> |
| 127 | <li><tt>felix.startlevel.bundle</tt> - The default start level for newly installed bundles; the default value is 1.</li> |
| 128 | <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> |
| 129 | </ul> |
| 130 | |
| 131 | |
| 132 | <p><a name="ApacheFelixFrameworkConfigurationProperties-launcher"></a></p> |
| 133 | |
| 134 | <h2><a name="ApacheFelixFrameworkConfigurationProperties-Launcherconfigurationproperties"></a>Launcher configuration properties</h2> |
| 135 | |
| 136 | <p>The following configuration properties are for the launcher:</p> |
| 137 | |
| 138 | <ul> |
| 139 | <li><tt>felix.auto.deploy.dir</tt> - Specifies the auto-deploy directory from which bundles are automatically deployed at framework startup. The default is the <tt>bundle/</tt> directory of the current directory.</li> |
| 140 | <li><tt>felix.auto.deploy.action</tt> |
| 141 | - Specifies a comma-delimited list of actions to be performed on bundle |
| 142 | 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>. |
| 143 | An undefined or blank value is equivalent to disabling auto-deploy |
| 144 | processing; there is no default value, so this value must be defined to |
| 145 | enable it.</li> |
| 146 | <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> |
| 147 | <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> |
| 148 | <li><tt>felix.shutdown.hook</tt> |
| 149 | - Specifies whether the launcher should install a shutdown hook to |
| 150 | cleanly shutdown the framework on process exit. The default value is <tt>true</tt>.</li> |
| 151 | </ul> |
| 152 | |
| 153 | |
| 154 | <p><a name="ApacheFelixFrameworkConfigurationProperties-migrating"></a></p> |
| 155 | |
| 156 | <h2><a name="ApacheFelixFrameworkConfigurationProperties-MigratingfromEarlierVersions"></a>Migrating from Earlier Versions</h2> |
| 157 | |
| 158 | <p>Apache Felix Framework <tt>2.0.0</tt> introduced significant |
| 159 | configuration property changes. This section describes the differences |
| 160 | from older versions of the framework.</p> |
| 161 | |
| 162 | <ul> |
| 163 | <li><b>Removed</b> |
| 164 | <ul> |
| 165 | <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> |
| 166 | <li><tt>felix.strict.osgi</tt> - No longer needed, since all non-specification features have been removed.</li> |
| 167 | <li><tt>felix.cache.dir</tt> - No longer needed, since Felix no longer uses bundle cache profiles for saving sets of bundles.</li> |
| 168 | <li><tt>felix.cache.profile</tt> - No longer needed, since the framework no longer uses bundle cache profiles for saving sets of bundles.</li> |
| 169 | <li><tt>felix.fragment.validation</tt> - No longer needed, since the framework supports fragments.</li> |
| 170 | </ul> |
| 171 | </li> |
| 172 | <li><b>Renamed</b> |
| 173 | <ul> |
| 174 | <li><tt>felix.cache.profiledir</tt> - The equivalent of this property is now named <tt>org.osgi.framework.storage</tt>.</li> |
| 175 | <li><tt>felix.startlevel.framework</tt> - The equivalent of this property is now named <tt>org.osgi.framework.startlevel.beginning</tt>.</li> |
| 176 | </ul> |
| 177 | </li> |
| 178 | <li><b>Introduced</b> |
| 179 | <ul> |
| 180 | <li><tt>org.osgi.framework.system.packages.extra</tt> - New property, as described above, added to align with standard framework API.</li> |
| 181 | <li><tt>org.osgi.framework.storage.clean</tt> - New property, as described above, added to align with standard framework API.</li> |
| 182 | <li><tt>felix.cache.rootdir</tt> - Introduced as a result of removing bundle profiles to help resolve relative bundle cache directories.</li> |
| 183 | </ul> |
| 184 | </li> |
| 185 | </ul> |
| 186 | |
| 187 | |
| 188 | <p>For the most part, these changes are minor and previous behavior |
| 189 | achieved from older configuration properties is either easily attained |
| 190 | with the new properties or no longer necessary.</p> |
| 191 | |
| 192 | <p><a name="ApacheFelixFrameworkConfigurationProperties-feedback"></a></p> |
| 193 | |
| 194 | <h2><a name="ApacheFelixFrameworkConfigurationProperties-Feedback"></a>Feedback</h2> |
| 195 | |
| 196 | <p>Subscribe to the Felix users mailing list by sending a message to <a href="mailto:users-subscribe@felix.apache.org" class="external-link" rel="nofollow">users-subscribe@felix.apache.org</a>; after subscribing, email questions or feedback to <a href="mailto:users@felix.apache.org" class="external-link" rel="nofollow">users@felix.apache.org</a>.</p> |
| 197 | </div> |
| 198 | </body></html> |