Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 2 | <html><head> |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 3 | |
| 4 | |
| 5 | |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 6 | <title>Apache Felix - Apache Felix Usage Documentation</title> |
Karl Pauls | 44987e5 | 2007-09-16 20:54:55 +0000 | [diff] [blame] | 7 | <link rel="stylesheet" href="apache-felix-usage-documentation_files/site.css" type="text/css" media="all"> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 8 | <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| 9 | </head><body> |
Karl Pauls | 4994cb0 | 2008-12-20 17:15:21 +0000 | [diff] [blame^] | 10 | <div class="title"><div class="logo"><a href="http://felix.apache.org/site/index.html"><img alt="Apache Felix" src="apache-felix-usage-documentation_files/logo.png" border="0"></a></div><div class="header"><a href="http://www.apache.org/"><img alt="Apache" src="apache-felix-usage-documentation_files/apache.png" border="0"></a></div></div> |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 11 | <div class="menu"> |
Karl Pauls | 4994cb0 | 2008-12-20 17:15:21 +0000 | [diff] [blame^] | 12 | <ul> |
Karl Pauls | 44987e5 | 2007-09-16 20:54:55 +0000 | [diff] [blame] | 13 | <li><a href="http://felix.apache.org/site/news.html" title="news">news</a></li> |
Karl Pauls | 44987e5 | 2007-09-16 20:54:55 +0000 | [diff] [blame] | 14 | <li><a href="http://felix.apache.org/site/license.html" title="license">license</a></li> |
| 15 | <li><span class="nobr"><a href="http://felix.apache.org/site/downloads.cgi" title="Visit page outside Confluence" rel="nofollow">downloads<sup><img class="rendericon" src="apache-felix-usage-documentation_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span></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> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 18 | <li><a href="http://felix.apache.org/site/contributing.html" title="Contributing">contributing</a></li> |
| 19 | <li><span class="nobr"><a href="http://www.apache.org/" title="Visit page outside Confluence" rel="nofollow">asf<sup><img class="rendericon" src="apache-felix-usage-documentation_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span></li> |
| 20 | <li><span class="nobr"><a href="http://www.apache.org/foundation/sponsorship.html" title="Visit page outside Confluence" rel="nofollow">sponsorship<sup><img class="rendericon" src="apache-felix-usage-documentation_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span></li> |
| 21 | <li><span class="nobr"><a href="http://www.apache.org/foundation/thanks.html" title="Visit page outside Confluence" rel="nofollow">sponsors<sup><img class="rendericon" src="apache-felix-usage-documentation_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span> |
| 22 | <!-- ApacheCon Ad --> |
| 23 | <iframe src="apache-felix-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 --> |
Karl Pauls | 4994cb0 | 2008-12-20 17:15:21 +0000 | [diff] [blame^] | 26 | </p></li></ul> </div> |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 27 | <div class="main"> |
| 28 | <h1><a name="ApacheFelixUsageDocumentation-ApacheFelixUsageDocumentation"></a>Apache Felix Usage Documentation</h1> |
| 29 | |
| 30 | <ul> |
| 31 | <li><a href="#ApacheFelixUsageDocumentation-startingfelix" title="starting-felix on Apache Felix Usage Documentation">Starting Felix</a></li> |
| 32 | <li><a href="#ApacheFelixUsageDocumentation-felixshell" title="felix-shell on Apache Felix Usage Documentation">Felix Shell</a> |
| 33 | <ul> |
| 34 | <li><a href="#ApacheFelixUsageDocumentation-installingbundles" title="installing-bundles on Apache Felix Usage Documentation">Installing Bundles</a></li> |
| 35 | <li><a href="#ApacheFelixUsageDocumentation-installingbundlesproxies" title="installing-bundles-proxies on Apache Felix Usage Documentation">Web Proxy Issues when Installing Bundles</a></li> |
| 36 | </ul> |
| 37 | </li> |
| 38 | <li><a href="#ApacheFelixUsageDocumentation-configuringfelix" title="configuring-felix on Apache Felix Usage Documentation">Configuring Felix</a> |
| 39 | <ul> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 40 | <li><a href="#ApacheFelixUsageDocumentation-migrating" title="migrating on Apache Felix Usage Documentation">Migrating from Earlier Versions</a></li> |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 41 | <li><a href="#ApacheFelixUsageDocumentation-propertysubstitution" title="property-substitution on Apache Felix Usage Documentation">System Property Substitution</a></li> |
| 42 | <li><a href="#ApacheFelixUsageDocumentation-defaultshell" title="default-shell on Apache Felix Usage Documentation">Changing the Command Shell User Interface</a></li> |
| 43 | </ul> |
| 44 | </li> |
| 45 | <li><a href="#ApacheFelixUsageDocumentation-configuringbundles" title="configuring-bundles on Apache Felix Usage Documentation">Configuring Bundles</a></li> |
| 46 | <li><a href="#ApacheFelixUsageDocumentation-feedback" title="feedback on Apache Felix Usage Documentation">Feedback</a></li> |
| 47 | </ul> |
| 48 | |
| 49 | |
| 50 | <p><a name="ApacheFelixUsageDocumentation-startingfelix"></a></p> |
| 51 | |
| 52 | <h2><a name="ApacheFelixUsageDocumentation-StartingFelix"></a>Starting Felix</h2> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 53 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 54 | <p>Start Felix from the installation directory by typing:</p> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 55 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 56 | <div class="preformatted"><div class="preformattedContent"> |
| 57 | <pre>java -jar bin/felix.jar |
| 58 | </pre> |
| 59 | </div></div> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 60 | |
| 61 | <p>After Felix starts, the text-based shell interface is started. It is possible to <a href="#ApacheFelixUsageDocumentation-defaultshell" title="default-shell on Apache Felix Usage Documentation">change your default shell user interface</a>. Felix stores all installed bundles into a bundle cache directory. By default, Felix creates 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-bundle-cache.html" title="Apache Felix Bundle Cache">Apache Felix Bundle Cache</a> document for more details.</p> |
| 62 | |
| 63 | <p>If you want to start Felix using a different bundle cache directory, you can start Felix like this:</p> |
| 64 | |
| 65 | <div class="preformatted"><div class="preformattedContent"> |
| 66 | <pre>java -jar bin/felix.jar <cache-path> |
| 67 | </pre> |
| 68 | </div></div> |
| 69 | |
| 70 | <p>Where <tt><cache-path></tt> is the path you want to use as the |
| 71 | bundle cache. If you specify a relative cache path, then it will be |
| 72 | treated as relative to the current working directory.</p> |
| 73 | |
| 74 | <table class="infoMacro" align="center" border="0" cellpadding="5" cellspacing="8" width="85%"><colgroup><col width="24"><col></colgroup><tbody><tr><td valign="top"><img src="apache-felix-usage-documentation_files/information.gif" alt="" align="absmiddle" border="0" height="16" width="16"></td><td><b class="strong">Useful Information</b><br> |
| 75 | <p>Previous versions of Felix prompted for a profile name when executed. The profile name was used to create a directory inside <tt>.felix/</tt> |
| 76 | in the users home directory. This approach allowed user's to have |
| 77 | different sets of bundles for different purposes, e.g., testing, |
| 78 | production, etc. If this behavior is still desired, it is very easy to |
| 79 | 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>" |
| 80 | as the bundle cache directory, where "${user.home}" is automatically |
| 81 | substituted with the appropriate system property by the launcher.</p></td></tr></tbody></table> |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 82 | |
| 83 | <p><a name="ApacheFelixUsageDocumentation-felixshell"></a></p> |
| 84 | |
| 85 | <h2><a name="ApacheFelixUsageDocumentation-FelixShell"></a>Felix Shell</h2> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 86 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 87 | <p>The main way to interact with Felix is via its shell service. Felix' |
| 88 | shell service is implemented as an OSGi service that, be default, uses |
| 89 | a simple text-based user interface. After starting Felix, type <tt>help</tt> into the shell to see the list of the available commands; these are the default commands:</p> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 90 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 91 | <div class="preformatted"><div class="preformattedContent"> |
| 92 | <pre>bundlelevel <level> <id> ... | <id> - set or get bundle start level. |
| 93 | cd [<base-URL>] - change or display base URL. |
| 94 | headers [<id> ...] - display bundle header properties. |
| 95 | help - display shell commands. |
| 96 | install <URL> [<URL> ...] - install bundle(s). |
| 97 | obr help - OSGi bundle repository. |
| 98 | packages [<id> ...] - list exported packages. |
| 99 | ps [-l | -u] - list installed bundles. |
| 100 | refresh - refresh packages. |
| 101 | services [-u] [-a] [<id> ...] - list registered or used services. |
| 102 | shutdown - shutdown Felix. |
| 103 | start <id> [<id> <URL> ...] - start bundle(s). |
| 104 | startlevel [<level>] - get or set framework start level. |
| 105 | stop <id> [<id> ...] - stop bundle(s). |
| 106 | uninstall <id> [<id> ...] - uninstall bundle(s). |
| 107 | update <id> [<URL>] - update bundle. |
| 108 | version - display version of framework. |
| 109 | </pre> |
| 110 | </div></div> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 111 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 112 | <p>For a detailed description of how to install bundles into Felix refer to the next <a href="#ApacheFelixUsageDocumentation-installingbundles" title="installing-bundles on Apache Felix Usage Documentation">sub-section</a>; the remainder of this section briefly describes shell behavior.</p> |
| 113 | |
| 114 | <p>Despite the fact that the Felix shell tries to mimic a typical Unix-like shell, it is actually quite limited. The notion of <tt>cd</tt>, |
| 115 | for example, is only used to specify a default base URL in order to |
| 116 | save typing. To illustrate, assume that you want to install several |
| 117 | bundles from a directory on your disk, you could type:</p> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 118 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 119 | <div class="preformatted"><div class="preformattedContent"> |
| 120 | <pre>cd file:/c:/projects/felix/bundle/ |
| 121 | </pre> |
| 122 | </div></div> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 123 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 124 | <p>After issuing this <tt>cd</tt> command, you no longer need to type |
| 125 | the complete URL for bundles located in the above directory, only the |
| 126 | name of the bundle JAR file is necessary. It is not possible to perform |
| 127 | an equivalent <tt>ls</tt> command to list the contents of the current |
| 128 | base URL, since this operation is not possible with URLs. To view all |
| 129 | currently installed bundles, use the <tt>ps</tt> command.</p> |
| 130 | |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 131 | <p>To exit the Felix shell, simply type <tt>stop 0</tt> to stop the |
| 132 | System Bundle; any installed bundles will automatically be reloaded the |
| 133 | next time you start the associated profile. Additionally, any active |
| 134 | bundles will be reactivated the next time you restart the framework |
| 135 | with the same bundle cache.</p> |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 136 | |
| 137 | <p><a name="ApacheFelixUsageDocumentation-installingbundles"></a></p> |
| 138 | |
| 139 | <h3><a name="ApacheFelixUsageDocumentation-InstallingBundles"></a>Installing Bundles</h3> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 140 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 141 | <p>A bundle is the OSGi term for a component for the OSGi framework. A |
| 142 | bundle is simply a JAR file containing a manifest and some combination |
| 143 | of Java classes, embedded JAR files, native code, and resources. A |
| 144 | bundle may provide some specific functionality for the user or it may |
| 145 | implement a service that other bundles can use; bundles can only use |
| 146 | functionality from other bundles through shared services and packages.</p> |
| 147 | |
| 148 | <p>Felix is packaged with four bundles, which are located in the <tt>bundle/</tt> |
| 149 | directory of the Felix installation directory. There are bundles for |
| 150 | the Felix shell service, a text-based shell service user interface, a |
| 151 | bundle repository service, and a simple example bundle. In addition to |
| 152 | these bundles, the bundle repository services provides access to many |
| 153 | other bundles for easy installation. The bundle repository service |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 154 | provides a shell command, 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> |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 155 | |
| 156 | <p>Before installing any bundles, it is important to understand how |
| 157 | bundles are manually deployed into the framework. Bundles are deployed |
| 158 | in two stages; first they are installed, then they are started. To |
| 159 | install a bundle use the <tt>install</tt> shell command followed by a bundle URL. For example, to install the <tt>simple.jar</tt> bundle included with Felix you type (assuming you have started Felix from its installation directory):</p> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 160 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 161 | <div class="preformatted"><div class="preformattedContent"> |
| 162 | <pre>install file:bundle/simple.jar |
| 163 | </pre> |
| 164 | </div></div> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 165 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 166 | <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> |
| 167 | shell command is used to list all installed bundles and to obtain the |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 168 | bundle's identifier. The following Felix shell session capture |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 169 | illustrates how to start the <tt>simple.jar</tt> bundle:</p> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 170 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 171 | <div class="preformatted"><div class="preformattedContent"> |
| 172 | <pre>-> install [file:bundle/simple] |
| 173 | -> ps |
| 174 | START LEVEL 1 |
| 175 | ID State Level Name |
| 176 | [ 0] [Active ] [ 0] System Bundle (0.8.0) |
| 177 | [ 1] [Active ] [ 1] Shell Service (0.8.0) |
| 178 | [ 2] [Active ] [ 1] Shell TUI (0.8.0) |
| 179 | [ 3] [Active ] [ 1] Bundle Repository (0.8.0) |
| 180 | [ 4] [Installed ] [ 1] Simple (0.8.0) |
| 181 | -> start 4 |
| 182 | Simple bundle 4 has started. |
| 183 | From native: Hello! |
| 184 | From embedded JAR: Hello! |
| 185 | Entry: META-INF/ |
| 186 | Entry: org/ |
| 187 | Entry: libfoo.so |
| 188 | The 'javax.servlet.http' package is not available. |
| 189 | The 'javax.servlet' package is not available. |
| 190 | -> |
| 191 | </pre> |
| 192 | </div></div> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 193 | |
| 194 | <p>The <tt>stop</tt> command is used to stop a bundle and the <tt>uninstall</tt> command is used to remove a bundle from the bundle cache. As an alternative to using the <tt>install</tt> and <tt>start</tt> commands explicitly, it is also possible to install and start a bundle in one step by using the <tt>start</tt> command with a bundle URL.</p> |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 195 | |
| 196 | <p>Bundles can be updated using the <tt>update</tt> command. The update |
| 197 | command allows you to specify an URL from which to retrieve the updated |
| 198 | bundle, but if one is not specified it will try to update the bundle |
| 199 | from the bundle's <tt>Bundle-UpdateLocation</tt> manifest attribute, if present, or the bundle's original location URL.</p> |
| 200 | |
| 201 | <p><b>Important:</b> When you <tt>update</tt> or <tt>uninstall</tt> a |
| 202 | bundle, the changes appear to take effect immediately, but in reality |
| 203 | the changes are only partially enacted. If a bundle is updated or |
| 204 | uninstalled and it was exporting packages, these packages are not |
| 205 | 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> |
| 206 | |
| 207 | <p>For an introduction to writing bundles and services, refer to the Felix bundle tutorial.</p> |
| 208 | |
| 209 | <p><a name="ApacheFelixUsageDocumentation-installingbundlesproxies"></a></p> |
| 210 | |
| 211 | <h3><a name="ApacheFelixUsageDocumentation-WebProxyIssueswhenInstallingBundles"></a>Web Proxy Issues when Installing Bundles</h3> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 212 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 213 | <p>If you use a proxy for Web access, then you may run into difficulty |
| 214 | using the Felix shell to install bundles from a remote URL. To remedy |
| 215 | this situation, certain system properties must be set to make Felix |
| 216 | work with your proxy. These properties are:</p> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 217 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 218 | <ul> |
| 219 | <li><tt>http.proxyHost</tt> - the name of the proxy host.</li> |
| 220 | <li><tt>http.proxyPort</tt> - the port of the proxy host.</li> |
| 221 | <li><tt>http.proxyAuth</tt> |
| 222 | - the user name and password to use when connecting to the proxy; this |
| 223 | string should be the user name and password separated by a colon (e.g., |
| 224 | <tt>rickhall:mypassword</tt>).</li> |
| 225 | </ul> |
| 226 | |
| 227 | |
| 228 | <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="#ApacheFelixUsageDocumentation-configuringfelix" title="configuring-felix on Apache Felix Usage Documentation">configuring Felix</a> for more information.</p> |
| 229 | |
| 230 | <p><a name="ApacheFelixUsageDocumentation-configuringfelix"></a></p> |
| 231 | |
| 232 | <h2><a name="ApacheFelixUsageDocumentation-ConfiguringFelix"></a>Configuring Felix</h2> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 233 | |
| 234 | <p>Felix uses properties to configure certain aspects of its behavior. The Felix launcher (i.e., <tt>java -jar bin/felix.jar</tt>) reads configuration properties from two different locations in the installation directory: <tt>conf/system.properties</tt> and <tt>conf/config.properties</tt>. Both files use standard Java property file syntax.</p> |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 235 | |
| 236 | <p>The <tt>conf/system.properties</tt> file provides a convenient |
| 237 | mechanism for defining Java system properties, but it is largely |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 238 | ignored by Felix, since Felix does not typically use system properties |
| 239 | for configuration purposes. Any properties placed in the <tt>conf/system.properties</tt> file are available at run time via <tt>System.getProperty()</tt> and <tt>BundleContext.getProperty()</tt>. It is also possible to specify a different location for the system properties file by using the <tt>felix.system.properties</tt> system property when executing Felix. For example:</p> |
| 240 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 241 | <div class="preformatted"><div class="preformattedContent"> |
| 242 | <pre>java -Dfelix.system.properties=file:/home/rickhall/system.properties -jar bin/felix.jar |
| 243 | </pre> |
| 244 | </div></div> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 245 | |
| 246 | <p>Nearly all Felix configuration occurs using properties in the <tt>conf/config.properties</tt> file. It is possible to change the location of the configuration properties file by specifying a new location value using the <tt>felix.config.properties</tt> |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 247 | system property. It is necessary to use a system property here since |
| 248 | Felix needs this value to start execution. As an example, the following |
| 249 | command could be used to specify a custom location for the |
| 250 | configuration properties file:</p> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 251 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 252 | <div class="preformatted"><div class="preformattedContent"> |
| 253 | <pre>java -Dfelix.config.properties=file:/home/rickhall/config.properties -jar bin/felix.jar |
| 254 | </pre> |
| 255 | </div></div> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 256 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 257 | <p>In this example the configuration properties will be read from the |
| 258 | specified URL. All remaining configuration properties should be defined |
| 259 | in the <tt>config.properties</tt> file itself. All configuration properties are accessible at run time via <tt>BundleContext.getProperty()</tt>.</p> |
| 260 | |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 261 | <p>Some configuration properties are handled by Felix' launcher, while |
| 262 | others are handled by the Felix framework itself. Regardless, both |
| 263 | launcher and framework configuration properties are placed in the <tt>conf/config.properties</tt> files.</p> |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 264 | |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 265 | <p>The following are launcher configuration properties:</p> |
| 266 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 267 | <ul> |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 268 | <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> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 269 | <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> |
| 270 | </ul> |
| 271 | |
| 272 | |
| 273 | <p>The following are framework configuration properties (properties starting with "<tt>felix</tt>" are specific to Felix, while those starting with "<tt>org.osgi</tt>" are standard OSGi properties):</p> |
| 274 | |
| 275 | <ul> |
| 276 | <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> |
| 277 | in the current working directory. The value should be a valid directory |
| 278 | name. The directory name can be either absolute or relative. Relative |
| 279 | directory names are relative to the current working directory. The |
| 280 | specified directory will be created if it does not exist.</li> |
| 281 | <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> |
| 282 | <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> |
| 283 | is set to a relative name, by default it is relative to the current |
| 284 | working directory. If this property is set, then it will be calculated |
| 285 | as being relative to the specified root directory.</li> |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 286 | <li><tt>felix.cache.bufsize</tt> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 287 | - Sets the buffer size to be used by the cache; the default value is |
| 288 | 4096. The integer value of this string provides control over the size |
| 289 | of the internal buffer of the disk cache for performance reasons.</li> |
| 290 | <li><tt>org.osgi.framework.system.packages</tt> |
| 291 | - Specifies a comma-delimited list of packages that should be exported |
| 292 | via the System Bundle from the parent class loader. The framework will |
| 293 | set this to a reasonable default. If the value is specified, it |
| 294 | replaces any default value.</li> |
| 295 | <li><tt>org.osgi.framework.system.packages.extra</tt> |
| 296 | - Specifies a comma-delimited list of packages that should be exported |
| 297 | via the System Bundle from the parent class loader in addition to the |
| 298 | 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> |
| 299 | <li><tt>org.osgi.framework.bootdelegation</tt> |
| 300 | - Specifies a comma-delimited list of packages that should be made |
| 301 | implicitly available to all bundles from the parent class loader. It is |
| 302 | recommended not to use this property since it breaks modularity. The |
| 303 | default value is empty.</li> |
| 304 | <li><tt>felix.systembundle.activators</tt> - A <tt>List</tt> of <tt>BundleActivator</tt> |
| 305 | instances that are started/stopped when the System Bundle is |
| 306 | started/stopped. The specified instances will receive the System |
Karl Pauls | 4994cb0 | 2008-12-20 17:15:21 +0000 | [diff] [blame^] | 307 | Bundle's <tt>BundleContext</tt> when invoked. (This property cannot be |
| 308 | set in the configuration file since it requires instances; it can only |
| 309 | be passed into Felix' constructor directly.)</li> |
| 310 | <li><tt>felix.log.logger</tt> - An instance of <tt>Logger</tt> |
| 311 | that the framework uses as its default logger. (This property cannot be |
| 312 | set in the configuration file since it requires an instance; it can |
| 313 | only be passed into Felix' constructor directly.)</li> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 314 | <li><tt>felix.log.level</tt> |
| 315 | - An integer value indicating the degree of logging reported by the |
| 316 | framework; the higher the value the more logging is reported. If zero |
| 317 | ('0') is specified, then logging is turned off completely. The log |
| 318 | levels match those specified in the OSGi Log Service (i.e., 1 = error, |
| 319 | 2 = warning, 3 = information, and 4 = debug). The default value is 1.</li> |
| 320 | <li><tt>org.osgi.framework.startlevel</tt> - The initial start level of the framework once it starts execution; the default value is 1.</li> |
| 321 | <li><tt>felix.startlevel.bundle</tt> - The default start level for newly installed bundles; the default value is 1.</li> |
| 322 | <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> |
| 323 | <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> |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 324 | </ul> |
| 325 | |
| 326 | |
| 327 | <p>The Felix installation contains a default <tt>conf/config.properties</tt> file for automatically starting the shell-related bundles.</p> |
| 328 | |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 329 | <p><a name="ApacheFelixUsageDocumentation-migrating"></a></p> |
| 330 | |
| 331 | <h3><a name="ApacheFelixUsageDocumentation-MigratingfromEarlierVersions"></a>Migrating from Earlier Versions</h3> |
| 332 | |
| 333 | <p>The release of Felix <tt>1.4.0</tt> introduced some configuration property changes. This section describes the differences from older versions of Felix.</p> |
| 334 | |
| 335 | <ul> |
| 336 | <li><b>Removed</b> |
| 337 | <ul> |
| 338 | <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> |
| 339 | <li><tt>felix.strict.osgi</tt> - No longer needed, since all non-specification features have been removed.</li> |
| 340 | <li><tt>felix.cache.dir</tt> - No longer needed, since Felix no longer uses bundle cache profiles for saving sets of bundles.</li> |
| 341 | <li><tt>felix.cache.profile</tt> - No longer needed, since Felix no longer uses bundle cache profiles for saving sets of bundles.</li> |
| 342 | </ul> |
| 343 | </li> |
| 344 | <li><b>Renamed</b> |
| 345 | <ul> |
| 346 | <li><tt>felix.cache.profiledir</tt> - The equivalent of this property is now named <tt>org.osgi.framework.storage</tt>.</li> |
| 347 | <li><tt>felix.startlevel.framework</tt> - The equivalent of this property is now named <tt>org.osgi.framework.startlevel</tt>.</li> |
| 348 | </ul> |
| 349 | </li> |
| 350 | <li><b>Introduced</b> |
| 351 | <ul> |
| 352 | <li><tt>org.osgi.framework.system.packages.extra</tt> - New property, as described above, added to align with standard framework API.</li> |
| 353 | <li><tt>org.osgi.framework.storage.clean</tt> - New property, as described above, added to align with standard framework API.</li> |
| 354 | <li><tt>felix.cache.rootdir</tt> - Introduced as a result of removing bundle profiles to help resolve relative bundle cache directories.</li> |
| 355 | <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> |
| 356 | </ul> |
| 357 | </li> |
| 358 | </ul> |
| 359 | |
| 360 | |
| 361 | <p>For the most part, these changes are minor and previous behavior |
| 362 | achieved from older configuration properties is either easily attained |
| 363 | with the new properties or no longer necessary.</p> |
| 364 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 365 | <p><a name="ApacheFelixUsageDocumentation-propertysubstitution"></a></p> |
| 366 | |
| 367 | <h3><a name="ApacheFelixUsageDocumentation-SystemPropertySubstituion"></a>System Property Substituion</h3> |
| 368 | <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> |
| 369 | is the name of a system property to substitute. When such a property |
| 370 | value is retrieved by a bundle, the system property value will be |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 371 | substituted into the bundle property value as appropriate. It is |
| 372 | possible to have nested system property substitution, in which case the |
| 373 | inner-most property is substituted first, then the next inner most, |
| 374 | until reaching the outer most.</p> |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 375 | |
| 376 | <p><a name="ApacheFelixUsageDocumentation-defaultshell"></a></p> |
| 377 | |
| 378 | <h3><a name="ApacheFelixUsageDocumentation-ChangingtheCommandShellUserInterface"></a>Changing the Command Shell User Interface</h3> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 379 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 380 | <p>Felix' shell service supports multiple user interface |
| 381 | implementations; the default shell user interface is text-based, but a |
| 382 | simple graphical shell is also available. To change the default shell |
| 383 | user interface, you must download the Shell GUI and Shell GUI Plugin |
| 384 | bundles. Then you must modify the <tt>felix.auto.start</tt> property in the <tt>conf/config.properties</tt> file of your Felix installation. For the text-based user interface, the property value should look like this:</p> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 385 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 386 | <div class="preformatted"><div class="preformattedContent"> |
| 387 | <pre>felix.auto.start.1=file:bundle/shell.jar file:bundle/shelltui.jar \ |
| 388 | file:bundle/bundlerepository.jar |
| 389 | </pre> |
| 390 | </div></div> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 391 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 392 | <p>This property value instructs Felix to automatically start the shell |
| 393 | service, the shell textual user interface, and the bundle repository. (<em>Note: |
| 394 | The "\" character at the end of the above line indicates that the |
| 395 | property value continues on the next line; it is also possible to |
| 396 | specify the property value on one line.</em>) For the GUI-based shell user interface, the property value should look something like this:</p> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 397 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 398 | <div class="preformatted"><div class="preformattedContent"> |
| 399 | <pre>felix.auto.start.1=file:bundle/shell.jar file:bundle/bundlerepository.jar \ |
| 400 | file:bundle/shellgui.jar file:bundle/shellplugin.jar |
| 401 | </pre> |
| 402 | </div></div> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 403 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 404 | <p>This property value instructs Felix to automatically start the shell |
| 405 | service, the bundle repository, the shell GUI, and the shell GUI |
| 406 | plugins.</p> |
| 407 | |
| 408 | <p><a name="ApacheFelixUsageDocumentation-configuringbundles"></a></p> |
| 409 | |
| 410 | <h2><a name="ApacheFelixUsageDocumentation-ConfiguringBundles"></a>Configuring Bundles</h2> |
Karl Pauls | f7d389c | 2008-11-06 16:22:54 +0000 | [diff] [blame] | 411 | |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 412 | <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>. |
| 413 | It is a good idea, when implementing bundles, to parameterize them with |
| 414 | properties where appropriate. To learn about the configuration options |
| 415 | for specific bundles, refer to the documentation that accompanies them.</p> |
| 416 | |
| 417 | <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> |
| 418 | at run time. The property file uses the standard Java property file |
| 419 | syntax (i.e., attribute-value pairs). For information on changing the |
| 420 | default location of this file, refer to the section on <a href="#ApacheFelixUsageDocumentation-configuringfelix" title="configuring-felix on Apache Felix Usage Documentation">configuring Felix</a>.</p> |
| 421 | |
| 422 | <p><a name="ApacheFelixUsageDocumentation-feedback"></a></p> |
| 423 | |
| 424 | <h2><a name="ApacheFelixUsageDocumentation-Feedback"></a>Feedback</h2> |
| 425 | |
Karl Pauls | 4994cb0 | 2008-12-20 17:15:21 +0000 | [diff] [blame^] | 426 | <p>Subscribe to the Felix users mailing list by sending a message to <span class="nobr"><a href="mailto:users-subscribe@felix.apache.org" title="Send mail to users-subscribe@felix.apache.org" rel="nofollow">users-subscribe@felix.apache.org<sup><img class="rendericon" src="apache-felix-usage-documentation_files/mail_small.gif" alt="" align="absmiddle" border="0" height="12" width="13"></sup></a></span>; after subscribing, email questions or feedback to <span class="nobr"><a href="mailto:users@felix.apache.org" title="Send mail to users@felix.apache.org" rel="nofollow">users@felix.apache.org<sup><img class="rendericon" src="apache-felix-usage-documentation_files/mail_small.gif" alt="" align="absmiddle" border="0" height="12" width="13"></sup></a></span>.</p> |
Richard S. Hall | 2cd5bed | 2007-07-16 20:32:41 +0000 | [diff] [blame] | 427 | </div> |
Karl Pauls | 4994cb0 | 2008-12-20 17:15:21 +0000 | [diff] [blame^] | 428 | </body></html> |