felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pa...@apache.org
Subject svn commit: r910114 [3/4] - in /felix/trunk/main.distribution: ./ conf/ doc/ doc/apache-felix-framework-launching-and-embedding_files/ doc/apache-felix-framework-launching-and-embedding_files/button_data/ doc/apache-felix-framework-usage-documentation_...
Date Sun, 14 Feb 2010 22:53:05 GMT
Added: felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation.html
URL: http://svn.apache.org/viewvc/felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation.html?rev=910114&view=auto
==============================================================================
--- felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation.html (added)
+++ felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation.html Sun Feb 14 22:52:56 2010
@@ -0,0 +1,399 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html><head>
+
+
+  
+    <title>Apache Felix - Apache Felix Framework Usage Documentation</title>
+    <link rel="stylesheet" href="apache-felix-framework-usage-documentation_files/site.css" type="text/css" media="all">
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+  </head><body>
+    <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>
+    <div class="menu">
+<ul>
+	<li><a href="http://felix.apache.org/site/news.html" title="news">news</a></li>
+	<li><a href="http://felix.apache.org/site/license.html" title="license">license</a></li>
+	<li><a href="http://felix.apache.org/site/downloads.cgi" rel="nofollow">downloads</a></li>
+	<li><a href="http://felix.apache.org/site/documentation.html" title="documentation">documentation</a></li>
+	<li><a href="http://felix.apache.org/site/mailinglists.html" title="mailinglists">mailing lists</a></li>
+	<li><a href="http://felix.apache.org/site/contributing.html" title="Contributing">contributing</a></li>
+	<li><a href="http://www.apache.org/" rel="nofollow">asf</a></li>
+	<li><a href="http://www.apache.org/foundation/sponsorship.html" rel="nofollow">sponsorship</a></li>
+	<li><a href="http://www.apache.org/foundation/thanks.html" rel="nofollow">sponsors</a>
+<!-- ApacheCon Ad -->
+<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>
+<p style="height: 100px;">
+<!-- ApacheCon Ad -->
+</p></li></ul> </div>
+    <div class="main">
+<h1><a name="ApacheFelixFrameworkUsageDocumentation-ApacheFelixFrameworkUsageDocumentation"></a>Apache Felix Framework Usage Documentation</h1>
+
+<ul>
+	<li><a href="#ApacheFelixFrameworkUsageDocumentation-downloadingframework">Downloading the Framework</a></li>
+	<li><a href="#ApacheFelixFrameworkUsageDocumentation-startingframework">Starting the Framework</a></li>
+	<li><a href="#ApacheFelixFrameworkUsageDocumentation-frameworkshell">Framework Shell</a>
+	<ul>
+		<li><a href="#ApacheFelixFrameworkUsageDocumentation-installingbundles">Installing Bundles</a></li>
+		<li><a href="#ApacheFelixFrameworkUsageDocumentation-installingbundlesproxies">Web Proxy Issues when Installing Bundles</a></li>
+	</ul>
+	</li>
+	<li><a href="#ApacheFelixFrameworkUsageDocumentation-autodeploy">Bundle Auto-Deploy</a></li>
+	<li><a href="#ApacheFelixFrameworkUsageDocumentation-configuringframework">Configuring the Framework</a>
+	<ul>
+		<li><a href="#ApacheFelixFrameworkUsageDocumentation-migrating">Migrating from Earlier Versions</a></li>
+		<li><a href="#ApacheFelixFrameworkUsageDocumentation-propertysubstitution">System Property Substitution</a></li>
+	</ul>
+	</li>
+	<li><a href="#ApacheFelixFrameworkUsageDocumentation-configuringbundles">Configuring Bundles</a></li>
+	<li><a href="#ApacheFelixFrameworkUsageDocumentation-feedback">Feedback</a></li>
+</ul>
+
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-downloadingframework"></a></p>
+
+<h2><a name="ApacheFelixFrameworkUsageDocumentation-DownloadingtheFramework"></a>Downloading the Framework</h2>
+
+<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>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-startingframework"></a></p>
+
+<h2><a name="ApacheFelixFrameworkUsageDocumentation-StartingtheFramework"></a>Starting the Framework</h2>
+
+<p>Start the framework from the installation directory by typing:</p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>java -jar bin/felix.jar
+</pre>
+</div></div>
+
+<p>The framework launcher starts the framework and installs a bundles contained in the <tt>bundle</tt>
+directory of the current directory. By default, the bundle directory
+contains a simple text-based shell to interact with the framework.
+Bundles installed into the framework are copied into a bundle cache
+directory for subsequent executions. By default, the framework 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-framework-bundle-cache.html" title="Apache Felix Framework Bundle Cache">Apache Felix Framework Bundle Cache</a> document for more details.</p>
+
+<p>If you want to start the framework using a different bundle cache directory, you can do so like this:</p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>java -jar bin/felix.jar &lt;cache-path&gt;
+</pre>
+</div></div>
+
+<p>Where <tt>&lt;cache-path&gt;</tt> is the path you want to use as the
+bundle cache. If you specify a relative cache path, then it will be
+treated as relative to the current working directory.</p>
+
+<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
+versions of the framework prompted for a profile name when executed.
+The profile name was used to create a directory inside <tt>.felix/</tt>
+in the user home directory. This approach allowed users to have
+different sets of bundles for different purposes, e.g., testing,
+production, etc. If this behavior is still desired, it is very easy to
+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>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-frameworkshell"></a></p>
+
+<h2><a name="ApacheFelixFrameworkUsageDocumentation-FrameworkShell"></a>Framework Shell</h2>
+
+<p>The main way to interact with the framework is via its shell. Felix'
+shell is implemented as an OSGi service that, be default, uses a simple
+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 &lt;command-name&gt;</tt> to get help for a specific command.</p>
+
+<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>
+to stop the System Bundle; any installed bundles will automatically be
+reloaded (and potentially restarted) the next time you launch with the
+associated cache.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-installingbundles"></a></p>
+
+<h3><a name="ApacheFelixFrameworkUsageDocumentation-InstallingBundles"></a>Installing Bundles</h3>
+
+<p>A bundle is the OSGi term for a component for the OSGi framework. A
+bundle is simply a JAR file containing a manifest and some combination
+of Java classes, embedded JAR files, native code, and resources. A
+bundle may provide some specific functionality for the user or it may
+implement a service that other bundles can use; bundles can only use
+functionality from other bundles through shared services and packages.</p>
+
+<p>The Felix framework is packaged with three bundles, which are located in the <tt>bundle/</tt>
+directory of the framework installation directory. There are bundles
+for the Felix shell service, a text-based shell service user interface,
+and a bundle repository service. In addition to these bundles, the
+bundle repository services provides access to other bundles for easy
+installation. The bundle repository service 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>
+
+<p>Before installing any bundles, it is important to understand how
+bundles are manually deployed into the framework. Bundles are deployed
+in two stages; first they are installed, then they are started. To
+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>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>install file:/path/to/bundle/bundle.jar
+</pre>
+</div></div>
+
+<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>
+shell command is used to list all installed bundles and to obtain the
+bundle's identifier. The following Felix shell session capture
+illustrates how to start the <tt>bundle.jar</tt> bundle:</p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>-&gt; install [file:bundle/simple]
+-&gt; ps
+START LEVEL 1
+   ID   State         Level  Name
+[   0] [Active     ] [    0] System Bundle (2.0.0)
+[   1] [Active     ] [    1] Shell Service (1.4.0)
+[   2] [Active     ] [    1] Shell TUI (1.4.0)
+[   3] [Active     ] [    1] Bundle Repository (1.4.0)
+[   4] [Installed  ] [    1] Bundle Example (1.0.0)
+-&gt; start 4
+Hello from Bundle 4.
+-&gt;
+</pre>
+</div></div>
+
+<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>
+
+<p>Bundles can be updated using the <tt>update</tt> command. The update
+command allows you to specify an URL from which to retrieve the updated
+bundle, but if one is not specified it will try to update the bundle
+from the bundle's <tt>Bundle-UpdateLocation</tt> manifest attribute, if present, or the bundle's original location URL.</p>
+
+<p><b>Important:</b> When you <tt>update</tt> or <tt>uninstall</tt> a
+bundle, the changes appear to take effect immediately, but in reality
+the changes are only partially enacted. If a bundle is updated or
+uninstalled and it was exporting packages, these packages are not
+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>
+
+<p>For an introduction to writing bundles and services, refer to the Felix bundle tutorial.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-installingbundlesproxies"></a></p>
+
+<h3><a name="ApacheFelixFrameworkUsageDocumentation-WebProxyIssueswhenInstallingBundles"></a>Web Proxy Issues when Installing Bundles</h3>
+
+<p>If you use a proxy for Web access, then you may run into difficulty
+using the Felix shell to install bundles from a remote URL. To remedy
+this situation, certain system properties must be set to make Felix
+work with your proxy. These properties are:</p>
+
+<ul>
+	<li><tt>http.proxyHost</tt> - the name of the proxy host.</li>
+	<li><tt>http.proxyPort</tt> - the port of the proxy host.</li>
+	<li><tt>http.proxyAuth</tt>
+- the user name and password to use when connecting to the proxy; this
+string should be the user name and password separated by a colon (e.g.,
+<tt>rickhall:mypassword</tt>).</li>
+</ul>
+
+
+<p>These system properties can be set directly on the command line when starting the JVM using the standard "<tt>-D&lt;prop&gt;=&lt;value&gt;</tt>" syntax or you can put them in the <tt>lib/system.properties</tt> file of your Felix installation; see the next section on <a href="#ApacheFelixFrameworkUsageDocumentation-configuringframework">configuring Felix</a> for more information.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-autodeploy"></a></p>
+
+<h2><a name="ApacheFelixFrameworkUsageDocumentation-BundleAutoDeploy"></a>Bundle Auto-Deploy</h2>
+
+<p>To minimize the amount of configuration necessary to install bundles
+when you launch the framework, the Felix launcher uses the concept of
+an "auto-deploy" directory. The Felix launcher deploys all bundles in
+the auto-deploy directory into the framework instance during startup.
+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>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>java -jar bin/felix.jar -b /path/to/dir
+</pre>
+</div></div>
+
+<p>Specifying an auto-deploy directory replaces the default directory,
+it does not augment it. The default deployment actions performed on the
+bundles in the auto-deploy directory are: install, update, and start.
+Both the location of the auto-deploy directory and the deployment
+actions performed can be controlled by the following configuration
+properties, respectively:</p>
+
+<ul>
+	<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>
+	<li><tt>felix.auto.deploy.action</tt>
+- Specifies the auto-deploy actions to be found on bundle 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>.
+If no actions are specified, then the auto-deploy directory is not
+processed. There is no default value for this property, but the default
+<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>
+</ul>
+
+
+<p>The next section describes how to set and use configuration properties.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-configuringframework"></a></p>
+
+<h2><a name="ApacheFelixFrameworkUsageDocumentation-ConfiguringtheFramework"></a>Configuring the Framework</h2>
+
+<p>Both the Felix framework and the launcher use configuration
+properties to alter their default behavior. The framework can only be
+configured by passing properties into its constructor, but the launcher
+provides a mechanism to configure the framework via a property file.
+The launcher The Felix framework uses properties to configure certain
+aspects of its behavior. The framework launcher reads configuration
+properties from <tt>conf/config.properties</tt>. This file uses standard Java property file syntax.</p>
+
+<p>The launcher also supports setting system properties via the <tt>conf/system.properties</tt>
+file. This file is purely for convenience when you need to repeatedly
+set system properties when running the framework. While the framework
+itself does not look at system properties, the launcher does copy any
+framework configuration properties found in the system properties into
+the framework configuration map, also for your convenience.</p>
+
+<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>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>java -Dfelix.config.properties=file:/home/rickhall/config.properties -jar bin/felix.jar
+</pre>
+</div></div>
+
+<p>Configuration and system properties are accessible at run time via <tt>BundleContext.getProperty()</tt>, but configuration properties override system properties.</p>
+
+<p>The following configuration properties are specifically for the launcher:</p>
+
+<ul>
+	<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>
+	<li><tt>felix.auto.deploy.action</tt>
+- Specifies the auto-deploy actions to be found on bundle 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>
+	<li><tt>felix.auto.install.&lt;n&gt;</tt> - Space-delimited list of bundle URLs to automatically install when Felix is started, where <tt>&lt;n&gt;</tt> is the start level into which the bundle will be installed (e.g., <tt>felix.auto.install.2</tt>).</li>
+	<li><tt>felix.auto.start.&lt;n&gt;</tt> - Space-delimited list of bundle URLs to automatically install and start when Felix is started, where <tt>&lt;n&gt;</tt> is the start level into which the bundle will be installed (e.g., <tt>felix.auto.start.2</tt>).</li>
+	<li><tt>felix.shutdown.hook</tt>
+- Specifies whether the launcher should install a shutdown hook to
+cleanly shutdown the framework on process exit. The default value is <tt>true</tt>.</li>
+</ul>
+
+
+<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>
+
+<ul>
+	<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>
+in the current working directory. The value should be a valid directory
+name. The directory name can be either absolute or relative. Relative
+directory names are relative to the current working directory. The
+specified directory will be created if it does not exist.</li>
+	<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>
+is set to a relative name, by default it is relative to the current
+working directory. If this property is set, then it will be calculated
+as being relative to the specified root directory.</li>
+	<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>
+	<li><tt>felix.cache.bufsize</tt>
+- Sets the buffer size to be used by the cache; the default value is
+4096. The integer value of this string provides control over the size
+of the internal buffer of the disk cache for performance reasons.</li>
+	<li><tt>org.osgi.framework.system.packages</tt>
+- Specifies a comma-delimited list of packages that should be exported
+via the System Bundle from the parent class loader. The framework will
+set this to a reasonable default. If the value is specified, it
+replaces any default value.</li>
+	<li><tt>org.osgi.framework.system.packages.extra</tt>
+- Specifies a comma-delimited list of packages that should be exported
+via the System Bundle from the parent class loader in addition to 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>
+	<li><tt>org.osgi.framework.bootdelegation</tt>
+- Specifies a comma-delimited list of packages that should be made
+implicitly available to all bundles from the parent class loader. It is
+recommended not to use this property since it breaks modularity. The
+default value is empty.</li>
+	<li><tt>felix.bootdelegation.implicit</tt>
+- Specifies whether the framework should try to guess when to
+implicitly boot delegate to ease integration with external code. The
+default value is <tt>true</tt>.</li>
+	<li><tt>felix.systembundle.activators</tt> - A <tt>List</tt> of <tt>BundleActivator</tt>
+instances that are started/stopped when the System Bundle is
+started/stopped. The specified instances will receive the System
+Bundle's <tt>BundleContext</tt> when invoked. (This property cannot be
+set in the configuration file since it requires instances; it can only
+be passed into Felix' constructor directly.)</li>
+	<li><tt>felix.log.logger</tt> - An instance of <tt>Logger</tt>
+that the framework uses as its default logger. (This property cannot be
+set in the configuration file since it requires an instance; it can
+only be passed into Felix' constructor directly.)</li>
+	<li><tt>felix.log.level</tt>
+- An integer value indicating the degree of logging reported by the
+framework; the higher the value the more logging is reported. If zero
+('0') is specified, then logging is turned off completely. The log
+levels match those specified in the OSGi Log Service (i.e., 1 = error,
+2 = warning, 3 = information, and 4 = debug). The default value is 1.</li>
+	<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>
+	<li><tt>felix.startlevel.bundle</tt> - The default start level for newly installed bundles; the default value is 1.</li>
+	<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>
+	<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>
+</ul>
+
+
+<p>The Felix framework installation contains a default <tt>conf/config.properties</tt> file for automatically starting the shell-related bundles.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-migrating"></a></p>
+
+<h3><a name="ApacheFelixFrameworkUsageDocumentation-MigratingfromEarlierVersions"></a>Migrating from Earlier Versions</h3>
+
+<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>
+
+<ul>
+	<li><b>Removed</b>
+	<ul>
+		<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>
+		<li><tt>felix.strict.osgi</tt> - No longer needed, since all non-specification features have been removed.</li>
+		<li><tt>felix.cache.dir</tt> - No longer needed, since Felix no longer uses bundle cache profiles for saving sets of bundles.</li>
+		<li><tt>felix.cache.profile</tt> - No longer needed, since Felix no longer uses bundle cache profiles for saving sets of bundles.</li>
+	</ul>
+	</li>
+	<li><b>Renamed</b>
+	<ul>
+		<li><tt>felix.cache.profiledir</tt> - The equivalent of this property is now named <tt>org.osgi.framework.storage</tt>.</li>
+		<li><tt>felix.startlevel.framework</tt> - The equivalent of this property is now named <tt>org.osgi.framework.startlevel.beginning</tt>.</li>
+	</ul>
+	</li>
+	<li><b>Introduced</b>
+	<ul>
+		<li><tt>org.osgi.framework.system.packages.extra</tt> - New property, as described above, added to align with standard framework API.</li>
+		<li><tt>org.osgi.framework.storage.clean</tt> - New property, as described above, added to align with standard framework API.</li>
+		<li><tt>felix.cache.rootdir</tt> - Introduced as a result of removing bundle profiles to help resolve relative bundle cache directories.</li>
+		<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>
+	</ul>
+	</li>
+</ul>
+
+
+<p>For the most part, these changes are minor and previous behavior
+achieved from older configuration properties is either easily attained
+with the new properties or no longer necessary.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-propertysubstitution"></a></p>
+
+<h3><a name="ApacheFelixFrameworkUsageDocumentation-SystemPropertySubstituion"></a>System Property Substituion</h3>
+
+<p>It is possible to use system properties to specify the values of properties in the <tt>conf/config.properties</tt> file. This is achieved through system property substitution, which is instigated by using <tt>${&lt;property&gt;</tt>} syntax, where <tt>&lt;property&gt;</tt>
+is the name of a system property to substitute. When such a property
+value is retrieved by a bundle, the system property value will be
+substituted into the bundle property value as appropriate. It is
+possible to have nested system property substitution, in which case the
+inner-most property is substituted first, then the next inner most,
+until reaching the outer most.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-configuringbundles"></a></p>
+
+<h2><a name="ApacheFelixFrameworkUsageDocumentation-ConfiguringBundles"></a>Configuring Bundles</h2>
+
+<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>.
+It is a good idea, when implementing bundles, to parameterize them with
+properties where appropriate. To learn about the configuration options
+for specific bundles, refer to the documentation that accompanies them.</p>
+
+<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>
+at run time. The property file uses the standard Java property file
+syntax (i.e., attribute-value pairs). For information on changing the
+default location of this file, refer to the section on <a href="#ApacheFelixFrameworkUsageDocumentation-configuringframework">configuring Felix</a>.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-feedback"></a></p>
+
+<h2><a name="ApacheFelixFrameworkUsageDocumentation-Feedback"></a>Feedback</h2>
+
+<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>
+    </div>
+  </body></html>

Added: felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/apache.png
URL: http://svn.apache.org/viewvc/felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/apache.png?rev=910114&view=auto
==============================================================================
Binary file - no diff available.

Propchange: felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/apache.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/button.html
URL: http://svn.apache.org/viewvc/felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/button.html?rev=910114&view=auto
==============================================================================
--- felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/button.html (added)
+++ felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/button.html Sun Feb 14 22:52:56 2010
@@ -0,0 +1,5 @@
+<html><head>
+<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1"><!-- ads start -->
+</head><body><a href="http://www.us.apachecon.com/c/acus2009/" target="_blank"><img src="button_data/2009-usa-125x125.png" title="ApacheCon US 2009" border="0" height="125" width="125"></a>
+<!-- ads end -->
+</body></html>
\ No newline at end of file

Added: felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/button_data/2008-usa-125x125.png
URL: http://svn.apache.org/viewvc/felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/button_data/2008-usa-125x125.png?rev=910114&view=auto
==============================================================================
Binary file - no diff available.

Propchange: felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/button_data/2008-usa-125x125.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/button_data/2009-europe-125x125.png
URL: http://svn.apache.org/viewvc/felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/button_data/2009-europe-125x125.png?rev=910114&view=auto
==============================================================================
Binary file - no diff available.

Propchange: felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/button_data/2009-europe-125x125.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/button_data/2009-usa-125x125.png
URL: http://svn.apache.org/viewvc/felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/button_data/2009-usa-125x125.png?rev=910114&view=auto
==============================================================================
Binary file - no diff available.

Propchange: felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/button_data/2009-usa-125x125.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/information.gif
URL: http://svn.apache.org/viewvc/felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/information.gif?rev=910114&view=auto
==============================================================================
Binary file - no diff available.

Propchange: felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/information.gif
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/linkext7.gif
URL: http://svn.apache.org/viewvc/felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/linkext7.gif?rev=910114&view=auto
==============================================================================
Binary file - no diff available.

Propchange: felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/linkext7.gif
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/logo.png
URL: http://svn.apache.org/viewvc/felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/logo.png?rev=910114&view=auto
==============================================================================
Binary file - no diff available.

Propchange: felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/logo.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/mail_small.gif
URL: http://svn.apache.org/viewvc/felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/mail_small.gif?rev=910114&view=auto
==============================================================================
Binary file - no diff available.

Propchange: felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/mail_small.gif
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/site.css
URL: http://svn.apache.org/viewvc/felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/site.css?rev=910114&view=auto
==============================================================================
--- felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/site.css (added)
+++ felix/trunk/main.distribution/doc/apache-felix-framework-usage-documentation_files/site.css Sun Feb 14 22:52:56 2010
@@ -0,0 +1,25 @@
+/* @override http://felix.apache.org/site/media.data/site.css */
+
+body { background-color: #ffffff; color: #3b3b3b; font-family: Tahoma, Arial, sans-serif; font-size: 10pt; line-height: 140% }
+h1, h2, h3, h4, h5, h6 { font-weight: normal; color: #000000; line-height: 100%; margin-top: 0px}
+h1 { font-size: 200% }
+h2 { font-size: 175% }
+h3 { font-size: 150% }
+h4 { font-size: 140% }
+h5 { font-size: 130% }
+h6 { font-size: 120% }
+a { color: #1980af }
+a:visited { color: #1980af }
+a:hover { color: #1faae9 }
+.title { position: absolute; left: 1px; right: 1px; top:25px; height: 81px; background: url(http://felix.apache.org/site/media.data/gradient.png) repeat-x; background-position: bottom; }
+.logo { position: absolute; width: 15em; height: 81px; text-align: center; }
+.header { text-align: right; margin-right: 20pt; margin-top: 30pt;}
+.menu { border-top: 10px solid #f9bb00; position: absolute; top: 107px; left: 1px; width: 15em; bottom: 0px; padding: 0px; background-color: #fcfcfc }
+.menu ul { background-color: #fdf5d9; list-style: none; padding-left: 4em; margin-top: 0px; padding-top: 2em; padding-bottom: 2em; margin-left: 0px; color: #4a4a43}
+.menu a { text-decoration: none; color: #4a4a43 }
+.main { position: absolute; border-top: 10px solid #cde0ea; top: 107px; left: 15em; right: 1px; margin-left: 2px; padding-right: 4em; padding-left: 1em; padding-top: 1em;}
+.code { background-color: #eeeeee; border: solid 1px black; padding: 0.5em }
+.code-keyword { color: #880000 }
+.code-quote { color: #008800 }
+.code-object { color: #0000dd }
+.code-java { margin: 0em }
\ No newline at end of file

Added: felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository.html
URL: http://svn.apache.org/viewvc/felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository.html?rev=910114&view=auto
==============================================================================
--- felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository.html (added)
+++ felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository.html Sun Feb 14 22:52:56 2010
@@ -0,0 +1,524 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html><head>
+
+
+  
+    <title>Apache Felix - Apache Felix OSGi Bundle Repository</title>
+    <link rel="stylesheet" href="apache-felix-osgi-bundle-repository_files/site.css" type="text/css" media="all">
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+  </head><body>
+    <div class="title"><div class="logo"><a href="http://felix.apache.org/site/index.html"><img alt="Apache Felix" src="apache-felix-osgi-bundle-repository_files/logo.png" border="0"></a></div><div class="header"><a href="http://www.apache.org/"><img alt="Apache" src="apache-felix-osgi-bundle-repository_files/apache.png" border="0"></a></div></div>
+    <div class="menu">
+<ul>
+	<li><a href="http://cwiki.apache.org/FELIX/news.html" title="news">news</a></li>
+	<li><a href="http://cwiki.apache.org/FELIX/license.html" title="license">license</a></li>
+	<li><a href="http://felix.apache.org/site/downloads.cgi" rel="nofollow">downloads</a></li>
+	<li><a href="http://cwiki.apache.org/FELIX/documentation.html" title="documentation">documentation</a></li>
+	<li><a href="http://cwiki.apache.org/FELIX/mailinglists.html" title="mailinglists">mailing lists</a></li>
+	<li><a href="http://cwiki.apache.org/FELIX/contributing.html" title="Contributing">contributing</a></li>
+	<li><a href="http://www.apache.org/" rel="nofollow">asf</a></li>
+	<li><a href="http://www.apache.org/foundation/sponsorship.html" rel="nofollow">sponsorship</a></li>
+	<li><a href="http://www.apache.org/foundation/thanks.html" rel="nofollow">sponsors</a>
+<!-- ApacheCon Ad -->
+<iframe src="apache-felix-osgi-bundle-repository_files/button.html" style="border-width: 0pt; float: left;" frameborder="0" height="135" scrolling="no" width="135"></iframe>
+<p style="height: 100px;">
+<!-- ApacheCon Ad -->
+</p></li></ul> </div>
+    <div class="main">
+<h1><a name="ApacheFelixOSGiBundleRepository-ApacheFelixOSGiBundleRepository(OBR)"></a>Apache Felix OSGi Bundle Repository (OBR)</h1>
+
+<div>
+<ul>
+    <li><a href="#ApacheFelixOSGiBundleRepository-Motivation">Motivation</a></li>
+    <li><a href="#ApacheFelixOSGiBundleRepository-Overview">Overview</a></li>
+    <li><a href="#ApacheFelixOSGiBundleRepository-OBRRepositoryFile">OBR Repository File</a></li>
+    <li><a href="#ApacheFelixOSGiBundleRepository-OBRServiceAPI">OBR Service API</a></li>
+    <li><a href="#ApacheFelixOSGiBundleRepository-OBRShellCommand">OBR Shell Command</a></li>
+<ul>
+    <li><a href="#ApacheFelixOSGiBundleRepository-obrhelp">obr help</a></li>
+    <li><a href="#ApacheFelixOSGiBundleRepository-obrlisturl">obr list-url</a></li>
+    <li><a href="#ApacheFelixOSGiBundleRepository-obraddurl">obr add-url</a></li>
+    <li><a href="#ApacheFelixOSGiBundleRepository-obrremoveurl">obr remove-url</a></li>
+    <li><a href="#ApacheFelixOSGiBundleRepository-obrlist">obr list</a></li>
+    <li><a href="#ApacheFelixOSGiBundleRepository-obrinfo">obr info</a></li>
+    <li><a href="#ApacheFelixOSGiBundleRepository-obrdeploy">obr deploy</a></li>
+    <li><a href="#ApacheFelixOSGiBundleRepository-obrstart">obr start</a></li>
+    <li><a href="#ApacheFelixOSGiBundleRepository-obrsource">obr source</a></li>
+    <li><a href="#ApacheFelixOSGiBundleRepository-obrjavadoc">obr javadoc</a></li>
+</ul>
+    <li><a href="#ApacheFelixOSGiBundleRepository-UsingOBRwithaProxy">Using OBR with a Proxy</a></li>
+    <li><a href="#ApacheFelixOSGiBundleRepository-BundleSourcePackaging">Bundle Source Packaging</a></li>
+    <li><a href="#ApacheFelixOSGiBundleRepository-NoteonOSGiR3Bundles">Note on OSGi R3 Bundles</a></li>
+    <li><a href="#ApacheFelixOSGiBundleRepository-Feedback">Feedback</a></li>
+</ul></div>
+
+<p><a name="ApacheFelixOSGiBundleRepository-motivation"></a></p>
+
+<h2><a name="ApacheFelixOSGiBundleRepository-Motivation"></a>Motivation</h2>
+
+<p>The goal of the Apache Felix OSGi Bundle Repository (OBR) is two-fold:</p>
+
+<ol>
+	<li>To simplify deploying and using available bundles with Felix.</li>
+	<li>To encourage independent bundle development so that communities of interest can grow.</li>
+</ol>
+
+
+<p>OBR achieves the first goal by providing a service that can
+automatically install a bundle, with its deployment dependencies, from
+a bundle repository. This makes it easier for people to experiment with
+existing bundles. The second goal is achieved by raising the visibility
+of the available bundles and providing access to both the executable
+bundle and its source code. Hopefully, by making OBR and the bundles
+themselves more visible, community members will be encouraged to
+provide or improve service implementations.</p>
+
+<p>Note: OBR provides access to the Felix' default bundle repository,
+but you can also use it to deploy your own bundles by creating a bundle
+repository meta-data file for your local bundles; see the <tt>obr list-url</tt>, <tt>obr add-url</tt>, and <tt>obr remove-url</tt> commands for more details.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository-overview"></a></p>
+
+<h2><a name="ApacheFelixOSGiBundleRepository-Overview"></a>Overview</h2>
+
+<p>For the most part, OBR is quite simple. An OBR "repository server"
+is not necessary, since all functionality may reside on the client
+side. OBR is able to provide its functionality by reading an XML-based
+meta-data file that describes the bundles available to it. The
+meta-data file essentially contains an XML encoding of the bundles'
+manifest information. From the meta-data, OBR is able to construct
+dependency information for deploying (i.e., installing and updating)
+bundles.</p>
+
+<p>OBR defines the following entities:</p>
+
+<ul>
+	<li><em><b>Repository Admin</b></em> - a service to access a federation of repositories.</li>
+	<li><em><b>Repository</b></em> - provides access to a set of resources.</li>
+	<li><em><b>Resource</b></em> - a description of an artifact to be installed on a device.</li>
+	<li><em><b>Capability</b></em> - a named set of properties.</li>
+	<li><em><b>Requirement</b></em> - an assertion on a capability.</li>
+	<li><em><b>Resolver</b></em> - an object to resolve resource dependencies and to deploy them.</li>
+	<li><em><b>Repository file</b></em> - XML file containing resource meta-data.</li>
+</ul>
+
+
+<p>The following diagram illustrates the relationships among these entities:</p>
+
+<p><img src="apache-felix-osgi-bundle-repository_files/obr-entities.png" align="absmiddle" border="0"></p>
+
+<p>The client has access to a federated set of repositories via the Repository Admin service; such as depicted in this view:</p>
+
+<p><img src="apache-felix-osgi-bundle-repository_files/obr-high-level.png" align="absmiddle" border="0"></p>
+
+<p><a name="ApacheFelixOSGiBundleRepository-repositoryfile"></a></p>
+
+<h2><a name="ApacheFelixOSGiBundleRepository-OBRRepositoryFile"></a>OBR Repository File</h2>
+
+<p>The OBR repository file is an XML-based representation of bundle
+meta-data. The goal is provide a generic model for describing
+dependencies among resources; as such, the term <em><b>resource</b></em> is used instead of <em><b>bundle</b></em> in the OBR repository syntax; a detailed description of the OBR meta-data format is available in the <a href="http://www2.osgi.org/download/rfc-0112_BundleRepository.pdf" rel="nofollow">OSGi RFC 112</a>
+document; this document is not completely in sync with the
+implementation, but the concepts are still correct. The following XML
+snippet depicts the overall structure of a repository file:</p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>&lt;repository presentationname="..." symbolicname="..." ... &gt;
+    &lt;resource&gt;
+        &lt;description&gt;...&lt;/description&gt;
+        &lt;size&gt;...&lt;/size&gt;
+        &lt;documentation&gt;...&lt;/documentation&gt;
+        &lt;source&gt;...&lt;/source&gt;
+        &lt;category id="..."/&gt;
+        &lt;capability&gt;...&lt;/capability&gt;
+        ...
+        &lt;requirement&gt;...&lt;/requirement&gt;
+        ...
+    &lt;/resource&gt;
+    ...
+&lt;/repository&gt;
+</pre>
+</div></div>
+
+<p>The above repository defines a set of available resources, each
+described by a set of meta-data. Some resource meta-data is purely
+intended for human consumption; the most important aspects relate to
+the generic capability/requirement model.</p>
+
+<p>A resource can provide any number of capabilities. A capability is a
+typed set of properties. For example, the following is an exported
+package capability:</p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>&lt;capability name='package'&gt;
+    &lt;p n='package' v='org.foo.bar'/&gt;
+    &lt;p n='version' t='version' v='1.0.0'/&gt;
+&lt;/capability&gt;
+</pre>
+</div></div>
+
+<p>This capability is of type 'package' and exports 'org.foo.bar' at
+version '1.0.0'. Conversely, a requirement is a typed LDAP query over a
+set of capability properties. For example, the following is an imported
+package requirement:</p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>&lt;require name='package' extend='false'
+    multiple='false' optional='false'
+    filter='(&amp;amp;(package=org.foo.bar)(version&amp;gt;=1.0.0))'&gt;
+    Import package org.foo.bar
+&lt;/require&gt;
+</pre>
+</div></div>
+
+<p>This requirement is of type 'package' and imports 'org.foo.bar' at
+versions greater than '1.0.0'. Although this syntax looks rather
+complicated with the '\&amp;' and '\&gt;=' syntax, it is simply the
+standard OSGi LDAP query syntax in XML form (additionally, Peter Kriens
+has created a tool called <tt>bindex</tt> to generate this meta-data from a bundle's manifest).</p>
+
+<p>With this generic dependency model, OBR is able to provide mappings
+for the various OSGi bundle dependencies; e.g., import/export package,
+provide/require bundle, host/fragment, import/export service, execution
+environment, and native code. In addition, it is possible for bundles
+to introduce arbitrary dependencies for custom purposes.</p>
+
+<p>Two other important pieces of meta-data are <tt>Bundle-SymbolicName</tt> and <tt>Bundle-Version</tt>;
+these are standard OSGi bundle manifest attributes that OBR uses to
+uniquely identify a bundle. For example, if you want to use OBR to
+update a locally installed bundle, OBR gets its symbolic name and
+version and searches the repository metadata for a matching symbolic
+name. If the matching symbolic name is found, then OBR checks if there
+is a newer version than the local copy using the bundle version number.
+Thus, the symbolic name plus bundle version forms a unique key to match
+locally installed bundles to remotely available bundles.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository-serviceapi"></a></p>
+
+<h2><a name="ApacheFelixOSGiBundleRepository-OBRServiceAPI"></a>OBR Service API</h2>
+
+<p>Typically, OBR service clients only need to interact with the
+Repository Admin service, which provides the mechanisms necessary to
+discover available resources. The Repository Admin interface is defined
+as follows:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">public</span> <span class="code-keyword">interface</span> RepositoryAdmin
+{
+    <span class="code-keyword">public</span> Resource[] discoverResources(<span class="code-object">String</span> filterExpr);
+    <span class="code-keyword">public</span> Resolver resolver();
+    <span class="code-keyword">public</span> Repository addRepository(URL repository)?
+        <span class="code-keyword">throws</span> Exception;
+    <span class="code-keyword">public</span> <span class="code-object">boolean</span> removeRepository(URL repository);
+    <span class="code-keyword">public</span> Repository[] listRepositories();
+    <span class="code-keyword">public</span> Resource getResource(<span class="code-object">String</span> respositoryId);
+}
+</pre>
+</div></div>
+
+<p>In order to resolve and deploy available resources, the Repository
+Admin provides Resolver instances, which are defined as follows:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">public</span> <span class="code-keyword">interface</span> Resolver
+{
+    <span class="code-keyword">public</span> void add(Resource resource);
+    <span class="code-keyword">public</span> Requirement[] getUnsatisfiedRequirements();
+    <span class="code-keyword">public</span> Resource[] getOptionalResources();
+    <span class="code-keyword">public</span> Requirement[] getReason(Resource resource);
+    <span class="code-keyword">public</span> Resource[] getResources(Requirement requirement);
+    <span class="code-keyword">public</span> Resource[] getRequiredResources();
+    <span class="code-keyword">public</span> Resource[] getAddedResources();
+    <span class="code-keyword">public</span> <span class="code-object">boolean</span> resolve();
+    <span class="code-keyword">public</span> void deploy(<span class="code-object">boolean</span> start);
+}
+</pre>
+</div></div>
+
+<p>When desired resources are discovered via the query mechanisms of
+the Repository Admin, they are added to a Resolver instance which will
+can be used to resolve all transitive dependencies and to reflect on
+any resolution result. The following code snippet depicts a typical
+usage scenario:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">RepositoryAdmin repoAdmin = ... <span class="code-comment">// Get repo admin service
+</span>Resolver resolver = repoAdmin.resolver();
+Resource resource = repoAdmin.discoverResources(filterStr);
+resolver.add(resource);
+<span class="code-keyword">if</span> (resolver.resolve())
+{
+    resolver.deploy(<span class="code-keyword">true</span>);
+}
+<span class="code-keyword">else</span>
+{
+    Requirement[] reqs = resolver.getUnsatisfiedRequirements();
+    <span class="code-keyword">for</span> (<span class="code-object">int</span> i = 0; i &lt; reqs.length; i++)
+    {
+        <span class="code-object">System</span>.out.println(<span class="code-quote">"Unable to resolve: "</span> + reqs[i]);
+    }
+}
+</pre>
+</div></div>
+
+<p>This code gets the Repository Admin service and then gets a Resolver
+instance from it. It then discovers an available resource and adds it
+to the resolver. Then it tries to resolve the resources dependencies.
+If successful it deploys the resource to the local framework instance;
+if not successful it prints the unsatisfied requirements.</p>
+
+<p>OBR's deployment algorithm appears simple at first glance, but it is
+actually somewhat complex due to the nature of deploying independently
+developed bundles. For example, in an ideal world, if an update for a
+bundle is made available, then updates for all of the bundles
+satisfying its dependencies are also made available. Unfortunately,
+this may not be the case, thus the deployment algorithm might have to
+install new bundles during an update to satisfy either new dependencies
+or updated dependencies that can no longer be satisfied by existing
+local bundles. In response to this type of scenario, the OBR deployment
+algorithm tries to favor updating existing bundles, if possible, as
+opposed to installing new bundles to satisfy dependencies.</p>
+
+<p>In the general case, OBR user's will not use the OBR API directly,
+but will use its functionality indirectly from another tool or user
+interface. For example, interactive access to OBR is available via a
+command for Felix' <a href="http://cwiki.apache.org/confluence/display/FELIX/Apache%20Felix%20Shell%20Service" title="Apache Felix Shell Service">shell service</a>. The OBR shell command is discussed in the next section.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository-shellcommand"></a></p>
+
+<h2><a name="ApacheFelixOSGiBundleRepository-OBRShellCommand"></a>OBR Shell Command</h2>
+
+<p>Besides providing a service API, OBR implements a Felix shell
+command for accessing its functionality. For the end user, the OBR
+shell command is accessed using the text-based or GUI-based user
+interfaces for Felix' shell service. This section describes the syntax
+for the OBR shell command.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository-obrhelp"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository-obrhelp"></a>obr help</h3>
+
+<p>Syntax:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>obr help [add-url | remove-url | list-url | list | info | deploy | start | source | javadoc]
+</pre>
+</div></div>
+<p>This command is used to display additional information about the other OBR commands.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository-obrlisturl"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository-obrlisturl"></a>obr list-url</h3>
+
+<p>Syntax:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>obr list-url
+</pre>
+</div></div>
+<p>This command gets the URLs to the repository files used by the Repository Admin.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository-obraddurl"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository-obraddurl"></a>obr add-url</h3>
+
+<p>Syntax:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>obr add-url [&lt;repository-file-url&gt; ...]
+</pre>
+</div></div>
+<p>This command adds a repository file to the set of repository files
+for which the Repository Admin service provides access. The repository
+file is represented as a URL. If the repository file URL is already in
+the Repository Admin's set of repository files, the request is treated
+like a reload operation.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository-obrremoveurl"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository-obrremoveurl"></a>obr remove-url</h3>
+
+<p>Syntax:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>obr remove-url [&lt;repository-file-url&gt; ...]
+</pre>
+</div></div>
+<p>This command removes a repository file to the set of repository
+files for which the Repository Admin service provides access. The
+repository file is represented as a URL.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository-obrlist"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository-obrlist"></a>obr list</h3>
+
+<p>Syntax:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>obr list [&lt;string&gt; ...]
+</pre>
+</div></div>
+<p>This command lists bundles available in the bundle repository. If no
+arguments are specified, then all available bundles are listed,
+otherwise any arguments are concatenated with spaces and used as a
+substring filter on the bundle names.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository-obrinfo"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository-obrinfo"></a>obr info</h3>
+
+<p>Syntax:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>obr info &lt;bundle-name&gt;[;&lt;version&gt;] ...
+</pre>
+</div></div>
+<p>This command displays the meta-data for the specified bundles. If a
+bundle's name contains spaces, then it must be surrounded by quotes. It
+is also possible to specify a precise version if more than one version
+exists, such as:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>obr info "Bundle Repository";1.0.0
+</pre>
+</div></div>
+<p>The above example retrieves the meta-data for version "1.0.0" of the bundle named "Bundle Repository".</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository-obrdeploy"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository-obrdeploy"></a>obr deploy</h3>
+
+<p>Syntax:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>obr deploy &lt;bundle-name&gt;[;&lt;version&gt;] ... | &lt;bundle-id&gt; ...
+</pre>
+</div></div>
+<p>This command tries to install or update the specified bundles and
+all of their dependencies by default. You can specify either the bundle
+name or the bundle identifier. If a bundle's name contains spaces, then
+it must be surrounded by quotes. It is also possible to specify a
+precise version if more than one version exists, such as:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>obr deploy "Bundle Repository";1.0.0
+</pre>
+</div></div>
+<p>For the above example, if version "1.0.0" of "Bundle Repository" is
+already installed locally, then the command will attempt to update it
+and all of its dependencies; otherwise, the command will install it and
+all of its dependencies.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository-obrstart"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository-obrstart"></a>obr start</h3>
+
+<p>Syntax:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>obr start [-nodeps] &lt;bundle-name&gt;[;&lt;version&gt;] ...
+</pre>
+</div></div>
+<p>This command installs and starts the specified bundles and all of
+their dependencies by default; use the "-nodeps" switch to ignore
+dependencies. If a bundle's name contains spaces, then it must be
+surrounded by quotes. If a specified bundle is already installed, then
+this command has no effect. It is also possible to specify a precise
+version if more than one version exists, such as:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>obr start "Bundle Repository";1.0.0
+</pre>
+</div></div>
+<p>The above example installs and starts the "1.0.0" version of the bundle named "Bundle Repository" and its dependencies.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository-obrsource"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository-obrsource"></a>obr source</h3>
+
+<p>Syntax:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>obr source [-x] &lt;local-dir&gt; &lt;bundle-name&gt;[;&lt;version&gt;] ...
+</pre>
+</div></div>
+<p>This command retrieves the source archives of the specified bundles
+and saves them to the specified local directory; use the "-x" switch to
+automatically extract the source archives. If a bundle name contains
+spaces, then it must be surrounded by quotes. It is also possible to
+specify a precise version if more than one version exists, such as:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>obr source /home/rickhall/tmp "Bundle Repository";1.0.0
+</pre>
+</div></div>
+<p>The above example retrieves the source archive of version "1.0.0" of
+the bundle named "Bundle Repository" and saves it to the specified
+local directory.</p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository-obrjavadoc"></a>obr javadoc</h3>
+
+<p>Syntax:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>obr javadoc [-x] &lt;local-dir&gt; &lt;bundle-name&gt;[;&lt;version&gt;] ...
+</pre>
+</div></div>
+<p>This command retrieves the javadoc archives of the specified bundles
+and saves them to the specified local directory; use the "-x" switch to
+automatically extract the javadoc archives. If a bundle name contains
+spaces, then it must be surrounded by quotes. It is also possible to
+specify a precise version if more than one version exists, such as:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>obr javadoc /home/rickhall/tmp "Bundle Repository";1.0.0
+</pre>
+</div></div>
+<p>The above example retrieves the javadoc archive of version "1.0.0"
+of the bundle named "Bundle Repository" and saves it to the specified
+local directory.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository-proxy"></a></p>
+
+<h2><a name="ApacheFelixOSGiBundleRepository-UsingOBRwithaProxy"></a>Using OBR with a Proxy</h2>
+
+<p>If you use a proxy for Web access, then OBR will not work for you in
+its default configuration; certain system properties must be set to
+enable OBR to work with a proxy. These properties are:</p>
+
+<ul>
+	<li>http.proxyHost - the name of the proxy host.</li>
+	<li>http.proxyPort - the port of the proxy host.</li>
+	<li>http.proxyAuth
+- the user name and password to use when connecting to the proxy; this
+string should be the user name and password separated by a colon (e.g.,
+rickhall:mypassword).</li>
+</ul>
+
+
+<p>These system properties can be set directly on the command line when
+starting the JVM using the standard "-D&lt;prop&gt;=&lt;value&gt;"
+syntax or you can put them in the lib/system.properties file of your
+Felix installation; see documentation on configuring Felix for more
+information.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository-sourcepackaging"></a></p>
+
+<h2><a name="ApacheFelixOSGiBundleRepository-BundleSourcePackaging"></a>Bundle Source Packaging</h2>
+
+<p>Coming soon...</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository-r3note"></a></p>
+
+<h2><a name="ApacheFelixOSGiBundleRepository-NoteonOSGiR3Bundles"></a>Note on OSGi R3 Bundles</h2>
+
+<p>In contrast to OSGi R4 the previous specifications, most notably R3, allowed bundles without the <tt>Bundle-SymbolicName</tt>
+header. The Felix OSGi Bundle Repository implementation heavily relies
+on the symbolic name being defined in bundles. As a consequence bundles
+without a symbolic name are not fully supported by the Bundle
+Repository:</p>
+
+<ul>
+	<li>Bundles installed in the framework are used by the Bundle
+Repository implementation to resolve dependencies regardless of whether
+they have a <tt>Bundle-SymbolicName</tt> header or not. Resolution of dependencies against the installed bundles takes place based on the <tt>Export-Package</tt> headers.</li>
+	<li>Bundles installed in the framework without a <tt>Bundle-SymbolicName</tt>
+header cannot be updated by the Bundle Repository implementation
+because updates from the bundle repository cannot be correlated to such
+"anonymous" bundles.</li>
+</ul>
+
+
+
+<p><a name="ApacheFelixOSGiBundleRepository-feedback"></a></p>
+
+<h2><a name="ApacheFelixOSGiBundleRepository-Feedback"></a>Feedback</h2>
+
+<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>
+    </div>
+  </body></html>

Added: felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/apache-felix-small.png
URL: http://svn.apache.org/viewvc/felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/apache-felix-small.png?rev=910114&view=auto
==============================================================================
Binary file - no diff available.

Propchange: felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/apache-felix-small.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/apache.png
URL: http://svn.apache.org/viewvc/felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/apache.png?rev=910114&view=auto
==============================================================================
Binary file - no diff available.

Propchange: felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/apache.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/button.html
URL: http://svn.apache.org/viewvc/felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/button.html?rev=910114&view=auto
==============================================================================
--- felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/button.html (added)
+++ felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/button.html Sun Feb 14 22:52:56 2010
@@ -0,0 +1,5 @@
+<html><head>
+<meta http-equiv="content-type" content="text/html; charset=UTF-8"><!-- ads start -->
+</head><body><a href="http://www.us.apachecon.com/c/acus2009/" target="_blank"><img src="button_data/2009-usa-125x125.png" title="ApacheCon US 2009" border="0" height="125" width="125"></a>
+<!-- ads end -->
+</body></html>
\ No newline at end of file

Added: felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/button_data/2009-usa-125x125.png
URL: http://svn.apache.org/viewvc/felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/button_data/2009-usa-125x125.png?rev=910114&view=auto
==============================================================================
Binary file - no diff available.

Propchange: felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/button_data/2009-usa-125x125.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/linkext7.gif
URL: http://svn.apache.org/viewvc/felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/linkext7.gif?rev=910114&view=auto
==============================================================================
Binary file - no diff available.

Propchange: felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/linkext7.gif
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/logo.png
URL: http://svn.apache.org/viewvc/felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/logo.png?rev=910114&view=auto
==============================================================================
Binary file - no diff available.

Propchange: felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/logo.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/mail_small.gif
URL: http://svn.apache.org/viewvc/felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/mail_small.gif?rev=910114&view=auto
==============================================================================
Binary file - no diff available.

Propchange: felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/mail_small.gif
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/obr-entities.png
URL: http://svn.apache.org/viewvc/felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/obr-entities.png?rev=910114&view=auto
==============================================================================
Binary file - no diff available.

Propchange: felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/obr-entities.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/obr-high-level.png
URL: http://svn.apache.org/viewvc/felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/obr-high-level.png?rev=910114&view=auto
==============================================================================
Binary file - no diff available.

Propchange: felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/obr-high-level.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/site.css
URL: http://svn.apache.org/viewvc/felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/site.css?rev=910114&view=auto
==============================================================================
--- felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/site.css (added)
+++ felix/trunk/main.distribution/doc/apache-felix-osgi-bundle-repository_files/site.css Sun Feb 14 22:52:56 2010
@@ -0,0 +1,25 @@
+/* @override http://felix.apache.org/site/media.data/site.css */
+
+body { background-color: #ffffff; color: #3b3b3b; font-family: Tahoma, Arial, sans-serif; font-size: 10pt; line-height: 140% }
+h1, h2, h3, h4, h5, h6 { font-weight: normal; color: #000000; line-height: 100%; margin-top: 0px}
+h1 { font-size: 200% }
+h2 { font-size: 175% }
+h3 { font-size: 150% }
+h4 { font-size: 140% }
+h5 { font-size: 130% }
+h6 { font-size: 120% }
+a { color: #1980af }
+a:visited { color: #1980af }
+a:hover { color: #1faae9 }
+.title { position: absolute; left: 1px; right: 1px; top:25px; height: 81px; background: url(http://felix.apache.org/site/media.data/gradient.png) repeat-x; background-position: bottom; }
+.logo { position: absolute; width: 15em; height: 81px; text-align: center; }
+.header { text-align: right; margin-right: 20pt; margin-top: 30pt;}
+.menu { border-top: 10px solid #f9bb00; position: absolute; top: 107px; left: 1px; width: 15em; bottom: 0px; padding: 0px; background-color: #fcfcfc }
+.menu ul { background-color: #fdf5d9; list-style: none; padding-left: 4em; margin-top: 0px; padding-top: 2em; padding-bottom: 2em; margin-left: 0px; color: #4a4a43}
+.menu a { text-decoration: none; color: #4a4a43 }
+.main { position: absolute; border-top: 10px solid #cde0ea; top: 107px; left: 15em; right: 1px; margin-left: 2px; padding-right: 4em; padding-left: 1em; padding-top: 1em;}
+.code { background-color: #eeeeee; border: solid 1px black; padding: 0.5em }
+.code-keyword { color: #880000 }
+.code-quote { color: #008800 }
+.code-object { color: #0000dd }
+.code-java { margin: 0em }
\ No newline at end of file



Mime
View raw message