Added some documentation and the change logs to framework and main sub-projects.
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@556724 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/framework/doc/changelog.txt b/framework/doc/changelog.txt
new file mode 100644
index 0000000..752da25
--- /dev/null
+++ b/framework/doc/changelog.txt
@@ -0,0 +1,52 @@
+Changes from 0.8.0-incubator to 1.0.0
+-------------------------------------
+
+* [2007-01-18] Added support for bundle header localization. (FELIX-27)
+* [2007-01-22] Modified framework resolver to support a generic
+ capability/requirement model.
+* [2007-01-22] Reorganized and centralized manifest parsing code and added
+ support for resolver's generic capability/requirement model. (FELIX-98)
+* [2007-01-22] Improved native library naming normalization. (FELIX-26)
+* [2007-01-23] No longer eagerly resolving classes loaded from modules
+ since this was causing verification errors with IBM J9.
+* [2007-01-25] Added some support for execution environment checking.
+ (FELIX-23)
+* [2007-01-29] Added support for getAllServiceReferences(). (FELIX-32)
+* [2007-01-31] Added Require-Bundle support to resolve using the generic
+ capability/requirement model of the resolver. (FELIX-28)
+* [2007-02-05] Fixed a bug in processor type normalization for x86-64
+ processors.
+* [2007-02-09] The resolver previously ignored packages that were pending
+ removal when resolving new bundles, now it does not.
+* [2007-02-09] Bundles are automatically refreshed when updated/uninstalled
+ if none of their exported packages are in use.
+* [2007-02-13] Added support for extension bundles. (FELIX-30)
+* [2007-03-02] Added a Bundle.getBundleContext() method until actual
+ support for OSGi R4.1.
+* [2007-04-26] Modified Bundle.findEntries() to return URLs to directory
+ entries as well as file entries.
+* [2007-05-06] Modified LDAP evaluator to special case the fact that
+ BigDecimal is not available in Foundation profile.
+* [2007-05-21] Made some performance improvements in LDAP evaluation.
+* [2007-05-22] Modified JAR file to include Service Tracker package.
+* [2007-05-22] Improved concurrency handling around checking for already
+ loaded classes and defining classes.
+* [2007-06-05] Modified resource URLs to use port number rather than
+ prepend information to the resource path.
+* [2007-06-13] Improved dynamic imports to cycle through all available
+ candidates when checking for class space consistency.
+* [2007-06-18] Improved service registry filtering based on class versions
+ to allow a bundle to register a service for a different version of class
+ that it can access.
+* [2007-06-21] Modified our "last ditch effort" to guess when to delegate
+ to the system bundle to make it a little more robust.
+* [2007-06-29] Fixed a bug in EventDispatcher that was causing asynchronous
+ events to not be fired after stopping the framework instance and creating
+ a new instance. (FELIX-314)
+* [2007-07-03] Fixed a bug in EventDispatcher that would not correctly
+ update a listener when it implemented multiple listener interfaces.
+* [2007-07-04] Modified Felix framework class to implement the Bundle
+ interface to improve the startup/shutdown sequence and to provide a
+ simplified API for creating framework instances.
+* [2007-07-11] Removed the PropertyResolver-related classes and now only
+ use Maps for configuration properties. (FELIX-324)
diff --git a/framework/doc/launching-and-embedding-apache-felix.html b/framework/doc/launching-and-embedding-apache-felix.html
new file mode 100644
index 0000000..60c7d56
--- /dev/null
+++ b/framework/doc/launching-and-embedding-apache-felix.html
@@ -0,0 +1,938 @@
+<!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 - Launching and Embedding Apache Felix</title><link rel="stylesheet" href="launching-and-embedding-apache-felix_files/site.css" type="text/css" media="all"><link rel="stylesheet" href="launching-and-embedding-apache-felix_files/print.css" type="text/css" media="print"><meta http-equiv="Content-Type" content="text/html;charset=UTF-8"></head><body linkifying="true">&t
+
+
+
+
+
+
+
+
+ <div class="title">
+ <a href="http://cwiki.apache.org/FELIX/index.html"><img alt="Apache Felix" src="launching-and-embedding-apache-felix_files/felix_logo.png" align="left" border="0"></a><a href="http://www.apache.org/"><img alt="Apache" src="launching-and-embedding-apache-felix_files/apache.png" align="right" border="0"></a>
+ </div>
+ <div class="menu">
+ <ul>
+ <li><a href="http://cwiki.apache.org/FELIX/index.html">home</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/news.html">news</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/status.html">status</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/license.html">license</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/downloads.html">downloads</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/documentation.html">documentation</a></li>
+ <li><a href="http://cwiki.apache.org/confluence/x/O-">wiki</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/committers.html">committers</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/mailinglists.html">mailing lists</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/faq.html">faq</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/roadmap.html">roadmap</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/sourcecode.html">source code</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/codingstandards.html">coding standards</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/issuetracking.html">issue tracking</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/dependencies.html">dependencies</a></li>
+ </ul>
+ </div>
+ <div class="main">
+<h1><a name="LaunchingandEmbeddingApacheFelix-LaunchingandEmbeddingApacheFelix"></a>Launching and Embedding Apache Felix</h1>
+
+<ul>
+ <li><a href="#LaunchingandEmbeddingApacheFelix-introduction" title="introduction on Launching and Embedding Apache Felix">Introduction</a></li>
+ <li><a href="#LaunchingandEmbeddingApacheFelix-overview" title="overview on Launching and Embedding Apache Felix">API Overview</a></li>
+ <li><a href="#LaunchingandEmbeddingApacheFelix-launching" title="launching on Launching and Embedding Apache Felix">Launching Felix</a>
+ <ul>
+ <li><a href="#LaunchingandEmbeddingApacheFelix-standardlauncher" title="standard-launcher on Launching and Embedding Apache Felix">Standard Felix Launcher</a></li>
+ <li><a href="#LaunchingandEmbeddingApacheFelix-customlauncher" title="custom-launcher on Launching and Embedding Apache Felix">Custom Felix Launcher</a></li>
+ </ul>
+ </li>
+ <li><a href="#LaunchingandEmbeddingApacheFelix-embedding" title="embedding on Launching and Embedding Apache Felix">Embedding Felix</a>
+ <ul>
+ <li><a href="#LaunchingandEmbeddingApacheFelix-configproperty" title="config-property on Launching and Embedding Apache Felix">Embedded Execution Configuration Property</a></li>
+ <li><a href="#LaunchingandEmbeddingApacheFelix-hostinteraction" title="host-interaction on Launching and Embedding Apache Felix">Host/Felix Interaction</a></li>
+ <li><a href="#LaunchingandEmbeddingApacheFelix-hostservices" title="host-services on Launching and Embedding Apache Felix">Providing Host Application Services</a></li>
+ <li><a href="#LaunchingandEmbeddingApacheFelix-hostserviceusage" title="host-service-usage on Launching and Embedding Apache Felix">Using Services Provided by Bundles</a>
+ <ul>
+ <li><a href="#LaunchingandEmbeddingApacheFelix-servicereflection" title="service-reflection on Launching and Embedding Apache Felix">Using Bundle Services via Reflection</a></li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li><a href="#LaunchingandEmbeddingApacheFelix-caveat" title="caveat on Launching and Embedding Apache Felix">Caveat</a></li>
+</ul>
+
+
+<p><a name="LaunchingandEmbeddingApacheFelix-introduction"></a></p>
+
+<h1><a name="LaunchingandEmbeddingApacheFelix-Introduction"></a>Introduction</h1>
+
+<p>The Apache Felix OSGi framework is intended to be easily launchable
+and embeddable. For example, Felix avoids the use of system properties
+for configuration, since these are globals that can cause interference
+if multiple framework instances are created in the same VM. Felix is
+also implemented to multiplex singleton facilities, like the URL stream
+handler factory. The goal is to make it possible to use Felix in as
+many scenarios as possible; however, this is still just a goal. In
+other words, this is a work in progress and if any issues arise, it
+would be greatly appreciated if they are brought to the attention of
+the Felix community. The next section provides a Felix API overview,
+while the remainder of the document is divided into two sections, one
+focusing on how to launch Felix and one focusing on how to embed Felix
+into a host application.</p>
+
+<p><a name="LaunchingandEmbeddingApacheFelix-overview"></a></p>
+
+<h1><a name="LaunchingandEmbeddingApacheFelix-APIOverview"></a>API Overview</h1>
+
+<p>The Felix class that implements the OSGi framework is <tt>org.apache.felix.framework.Felix</tt> or just <tt>Felix</tt> for short. The OSGi specification defines a special bundle, called the <em><b>System Bundle</b></em>,
+that represents the framework at run time and appears like any other
+bundle in the list of installed bundles. To make this notion even more
+intuitive, the <tt>Felix</tt> class implements the <tt>org.osgi.framework.Bundle</tt> interface, which is reiterated here:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">public</span> <span class="code-keyword">interface</span> Bundle
+{
+ <span class="code-keyword">public</span> BundleContext getBundleContext();
+ <span class="code-keyword">public</span> <span class="code-object">long</span> getBundleId();
+ <span class="code-keyword">public</span> URL getEntry(<span class="code-object">String</span> name);
+ <span class="code-keyword">public</span> Enumeration getEntryPaths(<span class="code-object">String</span> path);
+ <span class="code-keyword">public</span> Enumeration findEntries(<span class="code-object">String</span> path, <span class="code-object">String</span> filePattern, <span class="code-object">boolean</span> recurse);
+ <span class="code-keyword">public</span> Dictionary getHeaders();
+ <span class="code-keyword">public</span> Dictionary getHeaders(<span class="code-object">String</span> locale);
+ <span class="code-keyword">public</span> <span class="code-object">long</span> getLastModified();
+ <span class="code-keyword">public</span> <span class="code-object">String</span> getLocation();
+ <span class="code-keyword">public</span> URL getResource(<span class="code-object">String</span> name);
+ <span class="code-keyword">public</span> Enumeration getResources(<span class="code-object">String</span> name) <span class="code-keyword">throws</span> IOException;
+ <span class="code-keyword">public</span> ServiceReference[] getRegisteredServices();
+ <span class="code-keyword">public</span> ServiceReference[] getServicesInUse();
+ <span class="code-keyword">public</span> <span class="code-object">int</span> getState();
+ <span class="code-keyword">public</span> <span class="code-object">String</span> getSymbolicName();
+ <span class="code-keyword">public</span> <span class="code-object">boolean</span> hasPermission(<span class="code-object">Object</span> obj);
+ <span class="code-keyword">public</span> <span class="code-object">Class</span> loadClass(<span class="code-object">String</span> name) <span class="code-keyword">throws</span> ClassNotFoundException;
+ <span class="code-keyword">public</span> void start() <span class="code-keyword">throws</span> BundleException;
+ <span class="code-keyword">public</span> void stop() <span class="code-keyword">throws</span> BundleException;
+ <span class="code-keyword">public</span> void uninstall() <span class="code-keyword">throws</span> BundleException;
+ <span class="code-keyword">public</span> void update() <span class="code-keyword">throws</span> BundleException;
+ <span class="code-keyword">public</span> void update(InputStream is) <span class="code-keyword">throws</span> BundleException;
+}</pre>
+</div></div>
+
+<p>When you instantiate the <tt>Felix</tt> class, the resulting object is actually the System Bundle and can be cast to the <tt>Bundle</tt> interface. The <tt>start()</tt> method is used to start the framework instance, while the <tt>stop()</tt> method is used to asynchronously stop the framework instance. The <tt>Felix</tt> class also includes the following two additional public methods:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">public</span> class Felix <span class="code-keyword">extends</span> AbstractBundle
+{
+ <span class="code-keyword">public</span> Felix(Map configMutableMap, List activatorList);
+ <span class="code-keyword">public</span> void stopAndWait();
+}</pre>
+</div></div>
+
+<p>The first method is the constructor used to instantiate framework
+instances; the constructor accepts configuration properties and System
+Bundle activators, which are both described in more detail later. The <tt>stopAndWait()</tt> method is a synchronous version of the <tt>stop()</tt> method, used to stop the framework and block the calling thread until the framework is completely stopped.</p>
+
+<p><a name="LaunchingandEmbeddingApacheFelix-launching"></a></p>
+
+<h1><a name="LaunchingandEmbeddingApacheFelix-LaunchingFelix"></a>Launching Felix</h1>
+
+<p>Launching Felix is fairly simple and involves only three steps:</p>
+
+<ol>
+ <li>Defining some configuration properties.</li>
+ <li>Creating an instance of <tt>org.apache.felix.framework.Felix</tt> with the configuration properties.</li>
+ <li>Invoking the <tt>org.apache.felix.framework.Felix.start()</tt> method.</li>
+</ol>
+
+
+<p>The only configuration properties that are actually required to
+start Felix are ones that tell it where/how to locate the bundle cache
+profile directory where installed bundles will be cached. Felix' bundle
+cache implementation allows you to configure the location where bundles
+are cached using configuration properties. At a minimum, either a
+bundle cache profile name or directory must be specified; see the <a href="http://cwiki.apache.org/FELIX/apache-felix-bundle-cache.html" title="Apache Felix Bundle Cache">bundle cache document</a> for more detailed information on configuring the bundle cache.</p>
+
+<p>Besides configuration properties for the bundle cache, it is usually necessary to set the <tt>org.osgi.framework.system.packages</tt> configuration property to export packages from the class path, such as the OSGi interface classes (e.g., <tt>org.osgi.framework</tt>) on which all bundles depend. If you are creating a launcher for Felix, then the <tt>felix.auto.start</tt> configuration property may also be used to automatically install and start various bundles; see the <a href="http://cwiki.apache.org/FELIX/apache-felix-usage-documentation.html#ApacheFelixUsageDocumentation-configuringfelix" title="configuring-felix on Apache Felix Usage Documentation">usage document</a> for more information on configuring Felix and on the various configuration properties.</p>
+
+<p>The remainder of this section describes how the standard Felix
+launcher works as well as how to create a custom launcher for Felix.</p>
+
+<p><a name="LaunchingandEmbeddingApacheFelix-standardlauncher"></a></p>
+
+<h2><a name="LaunchingandEmbeddingApacheFelix-StandardFelixLauncher"></a>Standard Felix Launcher</h2>
+
+<p>The standard Felix launcher is very simple and is not intended to
+solve every possible requirement; it is intended to work for most
+standard situations. Most special launching requirements should be
+resolved by creating a custom launcher. This section describes how the
+standard launcher works. The following code represents the complete <tt>main()</tt> method of the standard launcher, each numbered comment will be described in more detail below:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">public</span> <span class="code-keyword">static</span> void main(<span class="code-object">String</span>[] argv) <span class="code-keyword">throws</span> Exception
+{
+ <span class="code-comment">// (1) Load system properties.
+</span> Main.loadSystemProperties();
+
+ <span class="code-comment">// (2) Read configuration properties.
+</span> Properties configProps = Main.loadConfigProperties();
+
+ <span class="code-comment">// (3) Copy framework properties from the system properties.
+</span> Main.copySystemProperties(configProps);
+
+ <span class="code-comment">// (4) See <span class="code-keyword">if</span> the profile name property was specified.
+</span> <span class="code-object">String</span> profileName = configProps.getProperty(BundleCache.CACHE_PROFILE_PROP);
+
+ <span class="code-comment">// (4) See <span class="code-keyword">if</span> the profile directory property was specified.
+</span> <span class="code-object">String</span> profileDirName = configProps.getProperty(BundleCache.CACHE_PROFILE_DIR_PROP);
+
+ <span class="code-comment">// Print welcome banner.
+</span> <span class="code-object">System</span>.out.println(<span class="code-quote">"\nWelcome to Felix."</span>);
+ <span class="code-object">System</span>.out.println(<span class="code-quote">"=================\n"</span>);
+
+ <span class="code-comment">// (5) If no profile or profile directory is specified in the
+</span> <span class="code-comment">// properties, then ask <span class="code-keyword">for</span> a profile name.
+</span> <span class="code-keyword">if</span> ((profileName == <span class="code-keyword">null</span>) && (profileDirName == <span class="code-keyword">null</span>))
+ {
+ <span class="code-object">System</span>.out.print(<span class="code-quote">"Enter profile name: "</span>);
+ BufferedReader in = <span class="code-keyword">new</span> BufferedReader(<span class="code-keyword">new</span> InputStreamReader(<span class="code-object">System</span>.in));
+ <span class="code-keyword">try</span>
+ {
+ profileName = in.readLine();
+ }
+ <span class="code-keyword">catch</span> (IOException ex)
+ {
+ <span class="code-object">System</span>.err.println(<span class="code-quote">"Could not read input."</span>);
+ <span class="code-object">System</span>.exit(-1);
+ }
+ <span class="code-object">System</span>.out.println("");
+ <span class="code-keyword">if</span> (profileName.length() != 0)
+ {
+ configProps.setProperty(BundleCache.CACHE_PROFILE_PROP, profileName);
+ }
+ }
+
+ <span class="code-comment">// (6) A profile directory or name must be specified.
+</span> <span class="code-keyword">if</span> ((profileDirName == <span class="code-keyword">null</span>) && (profileName.length() == 0))
+ {
+ <span class="code-object">System</span>.err.println(<span class="code-quote">"You must specify a profile name or directory."</span>);
+ <span class="code-object">System</span>.exit(-1);
+ }
+
+ <span class="code-keyword">try</span>
+ {
+ <span class="code-comment">// (7) Now create an instance of the framework.
+</span> m_felix = <span class="code-keyword">new</span> Felix(<span class="code-keyword">new</span> StringMap(configProps, <span class="code-keyword">false</span>), <span class="code-keyword">null</span>);
+ m_felix.start();
+ }
+ <span class="code-keyword">catch</span> (Exception ex)
+ {
+ <span class="code-object">System</span>.err.println(<span class="code-quote">"Could not create framework: "</span> + ex);
+ ex.printStackTrace();
+ <span class="code-object">System</span>.exit(-1);
+ }
+}</pre>
+</div></div>
+
+<p>The general steps of the standard launcher are quite straightforward:</p>
+
+<ol>
+ <li>Load any system properties specified in the <tt>system.properties</tt> file; this file is typically located in the <tt>conf/</tt> directory of the Felix installation directory, but it can be specified directly using the <tt>felix.system.properties</tt>
+system property. This file is not needed to launch Felix and is
+provided merely for convenience when system properties must be
+specified. The file is a standard Java properties file, but it also
+supports property substitution using <tt>${<property-name</tt>} syntax. Property substitution can be nested; only system properties will be used for substitution.</li>
+ <li>Load any configuration properties specified in the <tt>config.properties</tt> file; this file is typically located in the <tt>conf/</tt> directory of the Felix installation directory, but it can be specified directly using the <tt>felix.config.properties</tt>
+system property. This file is used to configure the Felix instance
+created by the launcher. The file is a standard Java properties file,
+but it also supports property substitution using "<tt>${<property-name</tt>}"
+syntax. Property substitution can be nested; configuration and system
+properties will be used for substitution with configuration properties
+having precedence.</li>
+ <li>For convenience, any configuration
+properties that are set as system properties will be copied into the
+set of configuration properties to provide an easy way to add to or
+override configuration properties specified in the <tt>config.properties</tt> file.</li>
+ <li>Try to load the profile name or profile directory configuration properties. At least one of these must be specified so that the <a href="http://cwiki.apache.org/FELIX/apache-felix-bundle-cache.html" title="Apache Felix Bundle Cache">bundle cache</a> knows where to save installed bundles.</li>
+ <li>If
+either the profile name or profile directory configuration property has
+not been specified, then ask the user to specify a profile name and add
+it to the current set of configuration properties.</li>
+ <li>Error if there is no profile name or profile directory.</li>
+ <li>Create the Felix instance passing in the configuration properties and then call <tt>start()</tt>.</li>
+</ol>
+
+
+<p>The framework is not active until the <tt>start()</tt> method is called. If no shell bundles are specified in the <tt>config.properties</tt>
+file or if there is difficulty locating the shell bundles that are
+specified, then it will appear as if the framework is hung, but it is
+actually running without any way to interact with it since the shell
+bundles provide the only means of interaction.</p>
+
+<p><a name="LaunchingandEmbeddingApacheFelix-customlauncher"></a></p>
+
+<h2><a name="LaunchingandEmbeddingApacheFelix-CustomFelixLauncher"></a>Custom Felix Launcher</h2>
+
+<p>This section creates a bare-bones launcher to demonstrate the
+minimum requirements for creating an interactive launcher for the Felix
+framework. This example uses the standard Felix shell bundles for
+interactivity, but any other bundles could be used instead. For
+example, the shell service and telnet bundles could be used to launch
+Felix and make it remotely accessible.</p>
+
+<p>This example launcher project has the following directory structure:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre>launcher/
+ lib/
+ org.apache.felix.framework-1.0.0.jar
+ bundle/
+ org.apache.felix.shell-1.0.0.jar
+ org.apache.felix.shell.tui-1.0.0.jar
+ src/
+ example/
+ Main.java
+</pre>
+</div></div>
+
+<p>The <tt>lib/</tt> directory contains the framework JAR file, which also contains the OSGi core interfaces. The <tt>bundle/</tt>
+directory contains the shell service and textual shell interface
+bundles that will be used for interacting with the framework instance.
+Note: If you do not launch Felix with interactive bundles, it will
+appear as if the framework instance is hung, but it is actually just
+sitting there waiting for someone to tell it to do something. The <tt>src/example/</tt> directory contains the following <tt>Main.java</tt> file, which is a very simplistic Felix launcher.</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">package</span> example;
+
+<span class="code-keyword">import</span> java.util.Map;
+<span class="code-keyword">import</span> org.osgi.framework.Constants;
+<span class="code-keyword">import</span> org.apache.felix.framework.Felix;
+<span class="code-keyword">import</span> org.apache.felix.framework.cache.BundleCache;
+<span class="code-keyword">import</span> org.apache.felix.framework.util.StringMap;
+<span class="code-keyword">import</span> org.apache.felix.framework.util.FelixConstants;
+
+<span class="code-keyword">public</span> class Main
+{
+ <span class="code-keyword">private</span> <span class="code-keyword">static</span> Felix m_felix = <span class="code-keyword">null</span>;
+
+ <span class="code-keyword">public</span> <span class="code-keyword">static</span> void main(<span class="code-object">String</span>[] argv) <span class="code-keyword">throws</span> Exception
+ {
+ <span class="code-comment">// Print welcome banner.
+</span> <span class="code-object">System</span>.out.println(<span class="code-quote">"\nWelcome to Felix."</span>);
+ <span class="code-object">System</span>.out.println(<span class="code-quote">"=================\n"</span>);
+
+ Map configMap = <span class="code-keyword">new</span> StringMap(<span class="code-keyword">false</span>);
+ configMap.put(Constants.FRAMEWORK_SYSTEMPACKAGES,
+ <span class="code-quote">"org.osgi.framework; version=1.3.0,"</span> +
+ <span class="code-quote">"org.osgi.service.packageadmin; version=1.2.0,"</span> +
+ <span class="code-quote">"org.osgi.service.startlevel; version=1.0.0,"</span> +
+ <span class="code-quote">"org.osgi.service.url; version=1.0.0"</span>);
+ configMap.put(FelixConstants.AUTO_START_PROP + <span class="code-quote">".1"</span>,
+ <span class="code-quote">"file:bundle/org.apache.felix.shell-1.0.0.jar "</span> +
+ <span class="code-quote">"file:bundle/org.apache.felix.shell.tui-1.0.0.jar"</span>);
+ configMap.put(BundleCache.CACHE_PROFILE_DIR_PROP, <span class="code-quote">"cache"</span>);
+
+ <span class="code-keyword">try</span>
+ {
+ <span class="code-comment">// Now create an instance of the framework.
+</span> m_felix = <span class="code-keyword">new</span> Felix(configMap, <span class="code-keyword">null</span>);
+ m_felix.start();
+ }
+ <span class="code-keyword">catch</span> (Exception ex)
+ {
+ <span class="code-object">System</span>.err.println(<span class="code-quote">"Could not create framework: "</span> + ex);
+ ex.printStackTrace();
+ <span class="code-object">System</span>.exit(-1);
+ }
+ }
+}</pre>
+</div></div>
+
+<p>This launcher has all information hard coded in it, unlike the
+default Felix launcher, which loads configuration properties from files
+and performs variable substitution. This simple launcher provides a
+good starting point if the features of the default launcher are not
+necessary. For example, if you want to create a launcher that
+automatically deletes the bundle cache directory each time it starts,
+then it is quite easy to figure out how to do that with this simple
+launcher.</p>
+
+<p>By breaking down the above source code into small chunks, it is quite easy to see what is going on.</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">Map configMap = <span class="code-keyword">new</span> StringMap(<span class="code-keyword">false</span>);</pre>
+</div></div>
+
+<p>This simply creates a map to hold configuration properties where the keys are strings and lookups are case insensitive.</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">configMap.put(Constants.FRAMEWORK_SYSTEMPACKAGES,
+ <span class="code-quote">"org.osgi.framework; version=1.3.0,"</span> +
+ <span class="code-quote">"org.osgi.service.packageadmin; version=1.2.0,"</span> +
+ <span class="code-quote">"org.osgi.service.startlevel; version=1.0.0,"</span> +
+ <span class="code-quote">"org.osgi.service.url; version=1.0.0"</span>);</pre>
+</div></div>
+
+<p>This sets the <tt>Constants.FRAMEWORK_SYSTEMPACKAGES</tt> configuration property (string value "<tt>org.osgi.framework.system.packages</tt>"),
+which specifies the class path packages the system bundle should
+export; this is how classes on the class path are made available to
+bundles. This example only exports the core OSGi API packages, but
+other JRE packages could also be added, such as <tt>javax.swing</tt>.
+For example, the default Felix launcher defines properties for all
+packages in various JRE versions (e.g., 1.3.x, 1.4.x, 1.5.x) and
+appends them to this property using property substitution.</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">configMap.put(FelixConstants.AUTO_START_PROP + <span class="code-quote">".1"</span>,
+ <span class="code-quote">"file:bundle/org.apache.felix.shell-1.0.0.jar "</span> +
+ <span class="code-quote">"file:bundle/org.apache.felix.shell.tui-1.0.0.jar"</span>);</pre>
+</div></div>
+
+<p>This sets the <tt>FelixConstants.AUTO_START_PROP</tt> configuration property (string value "<tt>felix.auto.start</tt>"),
+which is a space-delimited list of bundle URLs that the framework will
+automatically install and start when the framework starts. However,
+this property key cannot be used as is; it must be appended with a "."
+and then a number, where the number represents the start level for the
+bundle when it is installed. In this particular example, ".1" is
+appended to the property name, thus the two bundles will be installed
+into start level one. This example uses relative <tt>file:</tt> URLs, which will load the bundles from the <tt>bundle/</tt>
+directory assuming that the launcher is started from the root directory
+of the launcher project. It is also possible to specify absolute URLs
+or remote URLs.</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">configMap.put(BundleCache.CACHE_PROFILE_DIR_PROP, <span class="code-quote">"cache"</span>);</pre>
+</div></div>
+
+<p>This sets the last configuration property, <tt>BundleCache.CACHE_PROFILE_DIR_PROP</tt> (string value "<tt>felix.cache.profiledir</tt>"),
+which is a string that specifies the precise directory to be used as
+the bundle cache profile directory; the Felix bundle cache supports
+other properties to configure its behavior, but those are not covered
+here. In this example, the bundle cache profile directory is specified
+as a relative directory called "<tt>cache</tt>". Assuming that the
+launcher is executed from the root directory of the launcher project,
+then the bundle cache profile directory will be created in the root
+directory of the project.</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">m_felix = <span class="code-keyword">new</span> Felix(configMap, <span class="code-keyword">null</span>);
+ m_felix.start();</pre>
+</div></div>
+
+<p>The last steps create the framework instance and start it. The configuration property map is passed into the <tt>Felix</tt> constructor.</p>
+
+<p>The following command compiles the launcher when run from the root directory of the launcher project:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre>javac -d . -classpath lib/org.apache.felix.framework-1.0.0.jar src/example/Main.java
+</pre>
+</div></div>
+
+<p>After executing this command, an <tt>example/</tt> directory is
+created in the current directory, which contains the generated class
+file. The following command executes the simple launcher when run from
+the root directory of the launcher project:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre>java -cp .:lib/org.apache.felix.framework-1.0.0.jar example.Main
+</pre>
+</div></div>
+
+<p>After executing this command, a <tt>cache/</tt> directory is created that contains the installed bundles, which were installed from the <tt>bundle/</tt> directory.</p>
+
+<p><a name="LaunchingandEmbeddingApacheFelix-embedding"></a></p>
+
+<h1><a name="LaunchingandEmbeddingApacheFelix-EmbeddingFelix"></a>Embedding Felix</h1>
+
+<p>Embedding Felix into a host application is a simple way to provide a
+sophisticated extensibility mechanism (i.e., plugin system) to the host
+application. Embedding Felix is very similar to launching Felix as
+described above, the main difference is that the host application
+typically wants to interact with the framework instance and/or
+installed bundles/services from the outside. This is fairly easy to
+achieve with Felix, but there are some subtle issues to understand.
+This section presents the mechanisms for embedding Felix into a host
+application and the issues in doing so.</p>
+
+<p><a name="LaunchingandEmbeddingApacheFelix-configproperty"></a></p>
+
+<h2><a name="LaunchingandEmbeddingApacheFelix-EmbeddedExecutionConfigurationProperty"></a>Embedded Execution Configuration Property</h2>
+
+<p>When a Felix instance is embedded in a host application, the host
+application must inform the Felix instance that it is embedded. To do
+this, the host application sets the "<tt>felix.embedded.execution</tt>" configuration property to "<tt>true</tt>";
+this can be accomplished in the same way that all configuration
+properties are set, i.e., passing it into the Felix constructor via a
+map. This property specifically controls whether or not the Felix
+instance will shutdown the JVM (i.e., call <tt>System.exit()</tt> when
+the framework is shutdown. When embedding Felix it is generally not
+desirable for Felix to shutdown the JVM; therefore, by setting this
+property to "<tt>true</tt>" it can be avoided.</p>
+
+<p><a name="LaunchingandEmbeddingApacheFelix-hostinteraction"></a></p>
+
+<h2><a name="LaunchingandEmbeddingApacheFelix-Host/FelixInteraction"></a>Host/Felix Interaction</h2>
+
+<p>In the section on <a href="#LaunchingandEmbeddingApacheFelix-launching" title="launching on Launching and Embedding Apache Felix">launching</a> Felix above, the <tt>Felix</tt>
+constructor accepts two arguments, the first being the configuration
+properties for the framework, the second being a list of bundle
+activator instances. These bundle activator instances provide a
+convenient way for host applications to interact with the Felix
+framework.</p>
+
+<p>Each bundle activator instance passed into the constructor
+effectively becomes part of the System Bundle. This means that the
+start()/stop() method of each bundle activator instance in the passed
+in list gets invoked when the System Bundle's activator start()/stop()
+method gets invoked. Consequently, each bundle activator instance will
+be given the system bundle's <tt>BundleContext</tt> object so that they can interact with the framework externally. While it is possible to get the System Bundle's <tt>BundleContext</tt> object directly by calling <tt>Felix.getBundleContext()</tt>,
+this is generally not as convenient since it requires that you monitor
+when the System Bundle starts and/or stops. Consider following snippet
+of a bundle activator:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">public</span> class HostActivator <span class="code-keyword">implements</span> BundleActivator
+{
+ <span class="code-keyword">private</span> BundleContext m_context = <span class="code-keyword">null</span>;
+
+ <span class="code-keyword">public</span> void start(BundleContext context)
+ {
+ m_context = context;
+ }
+
+ <span class="code-keyword">public</span> void stop(BundleContext context)
+ {
+ m_context = <span class="code-keyword">null</span>;
+ }
+
+ <span class="code-keyword">public</span> Bundle[] getBundles()
+ {
+ <span class="code-keyword">if</span> (m_context != <span class="code-keyword">null</span>)
+ {
+ <span class="code-keyword">return</span> m_context.getBundles();
+ }
+ <span class="code-keyword">return</span> <span class="code-keyword">null</span>;
+ }
+}</pre>
+</div></div>
+
+<p>Given the above bundle activator, it is now possible to embed Felix
+into a host application and interact with it as the following snippet
+illustrates:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">public</span> class HostApplication
+{
+ <span class="code-keyword">private</span> HostActivator m_activator = <span class="code-keyword">null</span>;
+ <span class="code-keyword">private</span> Felix m_felix = <span class="code-keyword">null</span>;
+
+ <span class="code-keyword">public</span> HostApplication()
+ {
+ <span class="code-comment">// Create a <span class="code-keyword">case</span>-insensitive configuration property map.
+</span> Map configMap = <span class="code-keyword">new</span> StringMap(<span class="code-keyword">false</span>);
+ <span class="code-comment">// Configure the Felix instance to be embedded.
+</span> configMap.put(FelixConstants.EMBEDDED_EXECUTION_PROP, <span class="code-quote">"<span class="code-keyword">true</span>"</span>);
+ <span class="code-comment">// Add core OSGi packages to be exported from the class path
+</span> <span class="code-comment">// via the system bundle.
+</span> configMap.put(Constants.FRAMEWORK_SYSTEMPACKAGES,
+ <span class="code-quote">"org.osgi.framework; version=1.3.0,"</span> +
+ <span class="code-quote">"org.osgi.service.packageadmin; version=1.2.0,"</span> +
+ <span class="code-quote">"org.osgi.service.startlevel; version=1.0.0,"</span> +
+ <span class="code-quote">"org.osgi.service.url; version=1.0.0"</span>);
+ <span class="code-comment">// Explicitly specify the directory to use <span class="code-keyword">for</span> caching bundles.
+</span> configMap.put(BundleCache.CACHE_PROFILE_DIR_PROP, <span class="code-quote">"cache"</span>);
+
+ <span class="code-keyword">try</span>
+ {
+ <span class="code-comment">// Create host activator;
+</span> m_activator = <span class="code-keyword">new</span> HostActivator();
+ List list = <span class="code-keyword">new</span> ArrayList();
+ list.add(m_activator);
+
+ <span class="code-comment">// Now create an instance of the framework with
+</span> <span class="code-comment">// our configuration properties and activator.
+</span> m_felix = <span class="code-keyword">new</span> Felix(configMap, list);
+
+ <span class="code-comment">// Now start Felix instance.
+</span> m_felix.start();
+ }
+ <span class="code-keyword">catch</span> (Exception ex)
+ {
+ <span class="code-object">System</span>.err.println(<span class="code-quote">"Could not create framework: "</span> + ex);
+ ex.printStackTrace();
+ }
+ }
+
+ <span class="code-keyword">public</span> Bundle[] getInstalledBundles()
+ {
+ <span class="code-comment">// Use the system bundle activator to gain external
+</span> <span class="code-comment">// access to the set of installed bundles.
+</span> <span class="code-keyword">return</span> m_activator.getBundles();
+ }
+
+ <span class="code-keyword">public</span> void shutdownApplication()
+ {
+ <span class="code-comment">// Shut down the felix framework when stopping the
+</span> <span class="code-comment">// host application.
+</span> m_felix.shutdown();
+ }
+}</pre>
+</div></div>
+
+<p>Notice how the <tt>HostApplication.getInstalledBundles()</tt> method
+uses its activator instance to get access to the System Bundle's
+context in order to interact with the embedded Felix framework
+instance. This approach provides the foundation for all interaction
+between the host application and the embedded framework instance.</p>
+
+<p><a name="LaunchingandEmbeddingApacheFelix-hostservices"></a></p>
+
+<h2><a name="LaunchingandEmbeddingApacheFelix-ProvidingHostApplicationServices"></a>Providing Host Application Services</h2>
+
+<p>Providing services from the host application to bundles inside the
+embedded Felix framework instance follows the basic approach laid out
+in <a href="#LaunchingandEmbeddingApacheFelix-hostinteraction" title="host-interaction on Launching and Embedding Apache Felix">above</a>.
+The main complication for providing a host application service to
+bundles is the fact that both the host application and the bundles must
+be using the same class definitions for the service interface classes.
+Since the host application cannot import classes from a bundle, this
+means that the service interface classes <b>must</b> be accessible on
+the class path, typically as part of the host application itself. The
+host application then must export the service interface package via the
+system bundle so that bundles installed into the embedded framework
+instance can import it. This is achieved using the <tt>org.osgi.framework.system.packages</tt> configuration property previously presented.</p>
+
+<p>Consider the follow simple property lookup service:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">package</span> host.service.lookup;
+
+<span class="code-keyword">public</span> class Lookup
+{
+ <span class="code-keyword">public</span> <span class="code-object">Object</span> lookup(<span class="code-object">String</span> name);
+}</pre>
+</div></div>
+
+<p>This package is simply part of the host application, which is potentially packaged into a JAR file and started with the "<tt>java -jar</tt>"
+command. Now consider the following host application bundle activator,
+which will be used to register/unregister the property lookup service
+when the embedded framework instance starts/stops:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">package</span> host.core;
+
+<span class="code-keyword">import</span> java.util.Map;
+<span class="code-keyword">import</span> org.osgi.framework.BundleActivator;
+<span class="code-keyword">import</span> org.osgi.framework.BundleContext;
+<span class="code-keyword">import</span> org.osgi.framework.ServiceRegistration;
+<span class="code-keyword">import</span> host.service.lookup;
+
+<span class="code-keyword">public</span> class HostActivator <span class="code-keyword">implements</span> BundleActivator
+{
+ <span class="code-keyword">private</span> Map m_lookupMap = <span class="code-keyword">null</span>;
+ <span class="code-keyword">private</span> BundleContext m_context = <span class="code-keyword">null</span>;
+ <span class="code-keyword">private</span> ServiceRegistration m_registration = <span class="code-keyword">null</span>;
+
+ <span class="code-keyword">public</span> HostActivator(Map lookupMap)
+ {
+ <span class="code-comment">// Save a reference to the service's backing store.
+</span> m_lookupMap = lookupMap;
+ }
+
+ <span class="code-keyword">public</span> void start(BundleContext context)
+ {
+ <span class="code-comment">// Save a reference to the bundle context.
+</span> m_context = context;
+ <span class="code-comment">// Create a property lookup service implementation.
+</span> Lookup lookup = <span class="code-keyword">new</span> Lookup() {
+ <span class="code-keyword">public</span> <span class="code-object">Object</span> lookup(<span class="code-object">String</span> name)
+ {
+ <span class="code-keyword">return</span> m_lookupMap.get(name);
+ }
+ };
+ <span class="code-comment">// Register the property lookup service and save
+</span> <span class="code-comment">// the service registration.
+</span> m_registration = m_context.registerService(
+ Lookup.class.getName(), lookup, <span class="code-keyword">null</span>);
+ }
+
+ <span class="code-keyword">public</span> void stop(BundleContext context)
+ {
+ <span class="code-comment">// Unregister the property lookup service.
+</span> m_registration.unregister();
+ m_context = <span class="code-keyword">null</span>;
+ }
+}</pre>
+</div></div>
+
+<p>Given the above host application bundle activator, the following
+code snippet shows how the host application could create an embedded
+version of the Felix framework and provide the property lookup service
+to installed bundles:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">package</span> host.core;
+
+<span class="code-keyword">import</span> java.util.List;
+<span class="code-keyword">import</span> java.util.ArrayList;
+<span class="code-keyword">import</span> java.util.Map;
+<span class="code-keyword">import</span> java.util.HashMap;
+<span class="code-keyword">import</span> host.service.lookup.Lookup;
+<span class="code-keyword">import</span> org.apache.felix.framework.Felix;
+<span class="code-keyword">import</span> org.apache.felix.framework.util.FelixConstants;
+<span class="code-keyword">import</span> org.apache.felix.framework.util.StringMap;
+<span class="code-keyword">import</span> org.apache.felix.framework.cache.BundleCache;
+
+<span class="code-keyword">public</span> class HostApplication
+{
+ <span class="code-keyword">private</span> HostActivator m_activator = <span class="code-keyword">null</span>;
+ <span class="code-keyword">private</span> Felix m_felix = <span class="code-keyword">null</span>;
+ <span class="code-keyword">private</span> Map m_lookupMap = <span class="code-keyword">new</span> HashMap();
+
+ <span class="code-keyword">public</span> HostApplication()
+ {
+ <span class="code-comment">// Initialize the map <span class="code-keyword">for</span> the property lookup service.
+</span> m_lookupMap.put(<span class="code-quote">"name1"</span>, <span class="code-quote">"value1"</span>);
+ m_lookupMap.put(<span class="code-quote">"name2"</span>, <span class="code-quote">"value2"</span>);
+ m_lookupMap.put(<span class="code-quote">"name3"</span>, <span class="code-quote">"value3"</span>);
+ m_lookupMap.put(<span class="code-quote">"name4"</span>, <span class="code-quote">"value4"</span>);
+
+ <span class="code-comment">// Create a <span class="code-keyword">case</span>-insensitive configuration property map.
+</span> Map configMap = <span class="code-keyword">new</span> StringMap(<span class="code-keyword">false</span>);
+ <span class="code-comment">// Configure the Felix instance to be embedded.
+</span> configMap.put(FelixConstants.EMBEDDED_EXECUTION_PROP, <span class="code-quote">"<span class="code-keyword">true</span>"</span>);
+ <span class="code-comment">// Add the host provided service <span class="code-keyword">interface</span> <span class="code-keyword">package</span> and the core OSGi
+</span> <span class="code-comment">// packages to be exported from the class path via the system bundle.
+</span> configMap.put(Constants.FRAMEWORK_SYSTEMPACKAGES,
+ <span class="code-quote">"org.osgi.framework; version=1.3.0,"</span> +
+ <span class="code-quote">"org.osgi.service.packageadmin; version=1.2.0,"</span> +
+ <span class="code-quote">"org.osgi.service.startlevel; version=1.0.0,"</span> +
+ <span class="code-quote">"org.osgi.service.url; version=1.0.0,"</span> +
+ <span class="code-quote">"host.service.lookup; version=1.0.0"</span>);
+ <span class="code-comment">// Explicitly specify the directory to use <span class="code-keyword">for</span> caching bundles.
+</span> configMap.put(BundleCache.CACHE_PROFILE_DIR_PROP, <span class="code-quote">"cache"</span>);
+
+ <span class="code-keyword">try</span>
+ {
+ <span class="code-comment">// Create host activator;
+</span> m_activator = <span class="code-keyword">new</span> HostActivator(m_lookupMap);
+ List list = <span class="code-keyword">new</span> ArrayList();
+ list.add(m_activator);
+
+ <span class="code-comment">// Now create an instance of the framework with
+</span> <span class="code-comment">// our configuration properties and activator.
+</span> m_felix = <span class="code-keyword">new</span> Felix(configMap, list);
+
+ <span class="code-comment">// Now start Felix instance.
+</span> m_felix.start();
+ }
+ <span class="code-keyword">catch</span> (Exception ex)
+ {
+ <span class="code-object">System</span>.err.println(<span class="code-quote">"Could not create framework: "</span> + ex);
+ ex.printStackTrace();
+ }
+ }
+
+ <span class="code-keyword">public</span> void shutdownApplication()
+ {
+ <span class="code-comment">// Shut down the felix framework when stopping the
+</span> <span class="code-comment">// host application.
+</span> m_felix.shutdown();
+ }
+}</pre>
+</div></div>
+
+<p>Rather than having the host application bundle activator register
+the service, it is also possible for the the host application to simply
+get the bundle context from the bundle activator and register the
+service directly, but the presented approach is perhaps a little
+cleaner since it allows the host application to register/unregister the
+service when the system bundle starts/stops.</p>
+
+<p><a name="LaunchingandEmbeddingApacheFelix-hostserviceusage"></a></p>
+
+<h2><a name="LaunchingandEmbeddingApacheFelix-UsingServicesProvidedbyBundles"></a>Using Services Provided by Bundles</h2>
+
+<p>Using services provided by bundles follows the same general approach
+of using a host application bundle activator. The main complication for
+the host application using a service from a bundle is the fact that
+both the host application and the bundle must be using the same class
+definitions for the service interface classes. Since the host
+application cannot import classes from a bundle, this means that the
+service interface classes <b>must</b> be accessible on the class path,
+typically as part of the host application itself. The host application
+then must export the service interface package via the system bundle so
+that bundles installed into the embedded framework instance can import
+it. This is achieved using the <tt>org.osgi.framework.system.packages</tt> configuration property previously presented.</p>
+
+<p>Consider the following simple command service interface for which
+bundles provide implementations, such as might be used to create an
+extensible interactive shell:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">package</span> host.service.command;
+
+<span class="code-keyword">public</span> class Command
+{
+ <span class="code-keyword">public</span> <span class="code-object">String</span> getName();
+ <span class="code-keyword">public</span> <span class="code-object">String</span> getDescription();
+ <span class="code-keyword">public</span> <span class="code-object">boolean</span> execute(<span class="code-object">String</span> commandline);
+}</pre>
+</div></div>
+
+<p>This package is simply part of the host application, which is potentially packaged into a JAR file and started with the "<tt>java -jar</tt>"
+command. Now consider the previously introduced host application bundle
+activator below, which simply provides access to the system bundle
+context:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">package</span> host.core;
+
+<span class="code-keyword">import</span> org.osgi.framework.BundleActivator;
+<span class="code-keyword">import</span> org.osgi.framework.BundleContext;
+
+<span class="code-keyword">public</span> class HostActivator <span class="code-keyword">implements</span> BundleActivator
+{
+ <span class="code-keyword">private</span> BundleContext m_context = <span class="code-keyword">null</span>;
+
+ <span class="code-keyword">public</span> void start(BundleContext context)
+ {
+ m_context = context;
+ }
+
+ <span class="code-keyword">public</span> void stop(BundleContext context)
+ {
+ m_context = <span class="code-keyword">null</span>;
+ }
+
+ <span class="code-keyword">public</span> BundleContext getContext()
+ {
+ <span class="code-keyword">return</span> m_context;
+ }
+}</pre>
+</div></div>
+
+<p>With this bundle activator, the host application can command
+services provided by bundles installed inside its embedded Felix
+framework instance. The following code snippet illustrates one possible
+approach:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">package</span> host.core;
+
+<span class="code-keyword">import</span> java.util.List;
+<span class="code-keyword">import</span> java.util.ArrayList;
+<span class="code-keyword">import</span> java.util.Map;
+<span class="code-keyword">import</span> host.service.command.Command;
+<span class="code-keyword">import</span> org.apache.felix.framework.Felix;
+<span class="code-keyword">import</span> org.apache.felix.framework.util.FelixConstants;
+<span class="code-keyword">import</span> org.apache.felix.framework.util.StringMap;
+<span class="code-keyword">import</span> org.apache.felix.framework.cache.BundleCache;
+<span class="code-keyword">import</span> org.osgi.util.tracker.ServiceTracker;
+
+<span class="code-keyword">public</span> class HostApplication
+{
+ <span class="code-keyword">private</span> HostActivator m_activator = <span class="code-keyword">null</span>;
+ <span class="code-keyword">private</span> Felix m_felix = <span class="code-keyword">null</span>;
+ <span class="code-keyword">private</span> ServiceTracker m_tracker = <span class="code-keyword">null</span>;
+
+ <span class="code-keyword">public</span> HostApplication()
+ {
+ <span class="code-comment">// Create a <span class="code-keyword">case</span>-insensitive configuration property map.
+</span> Map configMap = <span class="code-keyword">new</span> StringMap(<span class="code-keyword">false</span>);
+ <span class="code-comment">// Configure the Felix instance to be embedded.
+</span> configMap.put(FelixConstants.EMBEDDED_EXECUTION_PROP, <span class="code-quote">"<span class="code-keyword">true</span>"</span>);
+ <span class="code-comment">// Add the bundle provided service <span class="code-keyword">interface</span> <span class="code-keyword">package</span> and the core OSGi
+</span> <span class="code-comment">// packages to be exported from the class path via the system bundle.
+</span> configMap.put(Constants.FRAMEWORK_SYSTEMPACKAGES,
+ <span class="code-quote">"org.osgi.framework; version=1.3.0,"</span> +
+ <span class="code-quote">"org.osgi.service.packageadmin; version=1.2.0,"</span> +
+ <span class="code-quote">"org.osgi.service.startlevel; version=1.0.0,"</span> +
+ <span class="code-quote">"org.osgi.service.url; version=1.0.0,"</span> +
+ <span class="code-quote">"host.service.command; version=1.0.0"</span>);
+ <span class="code-comment">// Explicitly specify the directory to use <span class="code-keyword">for</span> caching bundles.
+</span> configMap.put(BundleCache.CACHE_PROFILE_DIR_PROP, <span class="code-quote">"cache"</span>);
+
+ <span class="code-keyword">try</span>
+ {
+ <span class="code-comment">// Create host activator;
+</span> m_activator = <span class="code-keyword">new</span> HostActivator(m_lookupMap);
+ List list = <span class="code-keyword">new</span> ArrayList();
+ list.add(m_activator);
+
+ <span class="code-comment">// Now create an instance of the framework with
+</span> <span class="code-comment">// our configuration properties and activator.
+</span> m_felix = <span class="code-keyword">new</span> Felix(configMap, list);
+
+ <span class="code-comment">// Now start Felix instance.
+</span> m_felix.start();
+ }
+ <span class="code-keyword">catch</span> (Exception ex)
+ {
+ <span class="code-object">System</span>.err.println(<span class="code-quote">"Could not create framework: "</span> + ex);
+ ex.printStackTrace();
+ }
+
+ m_tracker = <span class="code-keyword">new</span> ServiceTracker(
+ m_activator.getContext(), Command.class.getName(), <span class="code-keyword">null</span>);
+ m_tracker.open();
+ }
+
+ <span class="code-keyword">public</span> <span class="code-object">boolean</span> execute(<span class="code-object">String</span> name, <span class="code-object">String</span> commandline)
+ {
+ <span class="code-comment">// See <span class="code-keyword">if</span> any of the currently tracked command services
+</span> <span class="code-comment">// match the specified command name, <span class="code-keyword">if</span> so then execute it.
+</span> <span class="code-object">Object</span>[] services = m_tracker.getServices();
+ <span class="code-keyword">for</span> (<span class="code-object">int</span> i = 0; (services != <span class="code-keyword">null</span>) && (i < services.length); i++)
+ {
+ <span class="code-keyword">try</span>
+ {
+ <span class="code-keyword">if</span> (((Command) services[i]).getName().equals(name))
+ {
+ <span class="code-keyword">return</span> ((Command) services[i]).execute(commandline);
+ }
+ }
+ <span class="code-keyword">catch</span> (Exception ex)
+ {
+ <span class="code-comment">// Since the services returned by the tracker could become
+</span> <span class="code-comment">// invalid at any moment, we will <span class="code-keyword">catch</span> all exceptions, log
+</span> <span class="code-comment">// a message, and then ignore faulty services.
+</span> <span class="code-object">System</span>.err.println(ex);
+ }
+ }
+ <span class="code-keyword">return</span> <span class="code-keyword">false</span>;
+ }
+
+ <span class="code-keyword">public</span> void shutdownApplication()
+ {
+ <span class="code-comment">// Shut down the felix framework when stopping the
+</span> <span class="code-comment">// host application.
+</span> m_felix.shutdown();
+ }
+}</pre>
+</div></div>
+
+<p>The above example is overly simplistic with respect to concurrency
+issues and error conditions, but it demonstrates the overall approach
+for using bundle-provided services from the host application. Note, to
+compile the above code you will need to compile against the Felix
+framework and Felix OSGi compendium JAR files, since the <tt>ServiceTracker</tt> classes are included in the compendium JAR file, not the framework JAR file.</p>
+
+<p><a name="LaunchingandEmbeddingApacheFelix-servicereflection"></a></p>
+
+<h3><a name="LaunchingandEmbeddingApacheFelix-UsingBundleServicesviaReflection"></a>Using Bundle Services via Reflection</h3>
+
+<p>It possible for the host application to use services provided by
+bundles without having access to the service interface classes and thus
+not needing to put the service interface classes on the class path. To
+do this, the host application uses the same general approach to acquire
+the system bundle context object, which it can use to look up service
+objects. Using either an LDAP filter or the service interface class
+name, the host application can retrieve the service object and then use
+standard Java reflection to invoke methods on the service object.</p>
+
+<p><a name="LaunchingandEmbeddingApacheFelix-caveat"></a></p>
+
+<h1><a name="LaunchingandEmbeddingApacheFelix-Caveat"></a>Caveat</h1>
+
+<p>The code in this document has not been thoroughly tested or even
+compiled and may be out of date with respect to the current Felix
+source code. If you find errors please report them so the that they can
+be corrected.</p>
+ </div>
+ </body></html>
\ No newline at end of file
diff --git a/framework/doc/launching-and-embedding-apache-felix_files/apache.png b/framework/doc/launching-and-embedding-apache-felix_files/apache.png
new file mode 100644
index 0000000..1bcce23
--- /dev/null
+++ b/framework/doc/launching-and-embedding-apache-felix_files/apache.png
Binary files differ
diff --git a/framework/doc/launching-and-embedding-apache-felix_files/felix_logo.png b/framework/doc/launching-and-embedding-apache-felix_files/felix_logo.png
new file mode 100644
index 0000000..d653a06
--- /dev/null
+++ b/framework/doc/launching-and-embedding-apache-felix_files/felix_logo.png
Binary files differ
diff --git a/framework/doc/launching-and-embedding-apache-felix_files/site.css b/framework/doc/launching-and-embedding-apache-felix_files/site.css
new file mode 100644
index 0000000..d60ada8
--- /dev/null
+++ b/framework/doc/launching-and-embedding-apache-felix_files/site.css
@@ -0,0 +1,21 @@
+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% }
+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: 0px; right: 0px; top: 0px; height: 107px; background: url(bg_header.png) repeat-x }
+.menu { position: absolute; top: 107px; left: 0px; width: 198px; bottom: 0px; padding: 0px; background-color: #fcfcfc }
+.menu ul { background-image: url(bg_menu.png); list-style: none; padding-left: 80px; margin-top: 0px; padding-top: 20px; padding-bottom: 20px; color: #4a4a43 }
+.menu a { text-decoration: none; color: #4a4a43 }
+.main { position: absolute; top: 107px; left: 220px; right: 80px }
+.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
diff --git a/main/doc/apache-felix-usage-documentation.html b/main/doc/apache-felix-usage-documentation.html
new file mode 100644
index 0000000..a1cbdd6
--- /dev/null
+++ b/main/doc/apache-felix-usage-documentation.html
@@ -0,0 +1,337 @@
+<!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 Usage Documentation</title><link rel="stylesheet" href="apache-felix-usage-documentation_files/site.css" type="text/css" media="all"><link rel="stylesheet" href="apache-felix-usage-documentation_files/print.css" type="text/css" media="print"><meta http-equiv="Content-Type" content="text/html;charset=UTF-8"></head><body linkifying="true">&t
+
+
+
+
+
+
+
+
+ <div class="title">
+ <a href="http://cwiki.apache.org/FELIX/index.html"><img alt="Apache Felix" src="apache-felix-usage-documentation_files/felix_logo.png" align="left" border="0"></a><a href="http://www.apache.org/"><img alt="Apache" src="apache-felix-usage-documentation_files/apache.png" align="right" border="0"></a>
+ </div>
+ <div class="menu">
+ <ul>
+ <li><a href="http://cwiki.apache.org/FELIX/index.html">home</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/news.html">news</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/status.html">status</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/license.html">license</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/downloads.html">downloads</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/documentation.html">documentation</a></li>
+ <li><a href="http://cwiki.apache.org/confluence/x/O-">wiki</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/committers.html">committers</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/mailinglists.html">mailing lists</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/faq.html">faq</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/roadmap.html">roadmap</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/sourcecode.html">source code</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/codingstandards.html">coding standards</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/issuetracking.html">issue tracking</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/dependencies.html">dependencies</a></li>
+ </ul>
+ </div>
+ <div class="main">
+<h1><a name="ApacheFelixUsageDocumentation-ApacheFelixUsageDocumentation"></a>Apache Felix Usage Documentation</h1>
+
+<ul>
+ <li><a href="#ApacheFelixUsageDocumentation-startingfelix" title="starting-felix on Apache Felix Usage Documentation">Starting Felix</a></li>
+ <li><a href="#ApacheFelixUsageDocumentation-felixshell" title="felix-shell on Apache Felix Usage Documentation">Felix Shell</a>
+ <ul>
+ <li><a href="#ApacheFelixUsageDocumentation-installingbundles" title="installing-bundles on Apache Felix Usage Documentation">Installing Bundles</a></li>
+ <li><a href="#ApacheFelixUsageDocumentation-installingbundlesproxies" title="installing-bundles-proxies on Apache Felix Usage Documentation">Web Proxy Issues when Installing Bundles</a></li>
+ </ul>
+ </li>
+ <li><a href="#ApacheFelixUsageDocumentation-configuringfelix" title="configuring-felix on Apache Felix Usage Documentation">Configuring Felix</a>
+ <ul>
+ <li><a href="#ApacheFelixUsageDocumentation-propertysubstitution" title="property-substitution on Apache Felix Usage Documentation">System Property Substitution</a></li>
+ <li><a href="#ApacheFelixUsageDocumentation-defaultshell" title="default-shell on Apache Felix Usage Documentation">Changing the Command Shell User Interface</a></li>
+ </ul>
+ </li>
+ <li><a href="#ApacheFelixUsageDocumentation-configuringbundles" title="configuring-bundles on Apache Felix Usage Documentation">Configuring Bundles</a></li>
+ <li><a href="#ApacheFelixUsageDocumentation-feedback" title="feedback on Apache Felix Usage Documentation">Feedback</a></li>
+</ul>
+
+
+<p><a name="ApacheFelixUsageDocumentation-startingfelix"></a></p>
+
+<h2><a name="ApacheFelixUsageDocumentation-StartingFelix"></a>Starting Felix</h2>
+<p>Start Felix from the installation directory by typing:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>java -jar bin/felix.jar
+</pre>
+</div></div>
+<p>After executing the above command, you will be prompted to enter a
+profile name; a profile is a simple way to organize sets of installed
+bundles and any arbitrary name will suffice. Entering the same profile
+name for subsequent executions of Felix will restore the installed
+bundles associated with that profile. By default, Felix creates a
+directory, called <tt>.felix</tt>, in your home directory and inside
+of this directory Felix creates a separate sub-directory for each
+profile; this behavior is configurable, see the <a href="http://cwiki.apache.org/FELIX/apache-felix-bundle-cache.html" title="Apache Felix Bundle Cache">Apache Felix Bundle Cache</a>
+document for more details. After you have specified a profile name, 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>.</p>
+
+<p><a name="ApacheFelixUsageDocumentation-felixshell"></a></p>
+
+<h2><a name="ApacheFelixUsageDocumentation-FelixShell"></a>Felix Shell</h2>
+<p>The main way to interact with Felix is via its shell service. Felix'
+shell service is implemented as an OSGi service that, be default, uses
+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>
+<div class="preformatted"><div class="preformattedContent">
+<pre>bundlelevel <level> <id> ... | <id> - set or get bundle start level.
+cd [<base-URL>] - change or display base URL.
+headers [<id> ...] - display bundle header properties.
+help - display shell commands.
+install <URL> [<URL> ...] - install bundle(s).
+obr help - OSGi bundle repository.
+packages [<id> ...] - list exported packages.
+ps [-l | -u] - list installed bundles.
+refresh - refresh packages.
+services [-u] [-a] [<id> ...] - list registered or used services.
+shutdown - shutdown Felix.
+start <id> [<id> <URL> ...] - start bundle(s).
+startlevel [<level>] - get or set framework start level.
+stop <id> [<id> ...] - stop bundle(s).
+uninstall <id> [<id> ...] - uninstall bundle(s).
+update <id> [<URL>] - update bundle.
+version - display version of framework.
+</pre>
+</div></div>
+<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>
+
+<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>,
+for example, is only used to specify a default base URL in order to
+save typing. To illustrate, assume that you want to install several
+bundles from a directory on your disk, you could type:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>cd file:/c:/projects/felix/bundle/
+</pre>
+</div></div>
+<p>After issuing this <tt>cd</tt> command, you no longer need to type
+the complete URL for bundles located in the above directory, only the
+name of the bundle JAR file is necessary. It is not possible to perform
+an equivalent <tt>ls</tt> command to list the contents of the current
+base URL, since this operation is not possible with URLs. To view all
+currently installed bundles, use the <tt>ps</tt> command.</p>
+
+<p>To exit the Felix shell, simply type <tt>shutdown</tt>; any bundles
+that are loaded will automatically be reloaded the next time you start
+the associated profile. Additionally, any bundles that are active, will
+be reactivated the next time you start the associated profile.</p>
+
+<p><a name="ApacheFelixUsageDocumentation-installingbundles"></a></p>
+
+<h3><a name="ApacheFelixUsageDocumentation-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>Felix is packaged with four bundles, which are located in the <tt>bundle/</tt>
+directory of the Felix installation directory. There are bundles for
+the Felix shell service, a text-based shell service user interface, a
+bundle repository service, and a simple example bundle. In addition to
+these bundles, the bundle repository services provides access to many
+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://cwiki.apache.org/FELIX/apache-felix-osgi-bundle-repository-obr.html" title="Apache Felix OSGi Bundle Repository (OBR)">Apache Felix OSGi Bundle Repository (OBR)</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 the <tt>simple.jar</tt> bundle included with Felix you type (assuming you have started Felix from its installation directory):</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>install file:bundle/simple.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 Oscar shell session capture
+illustrates how to start the <tt>simple.jar</tt> bundle:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>-> install [file:bundle/simple]
+-> ps
+START LEVEL 1
+ ID State Level Name
+[ 0] [Active ] [ 0] System Bundle (0.8.0)
+[ 1] [Active ] [ 1] Shell Service (0.8.0)
+[ 2] [Active ] [ 1] Shell TUI (0.8.0)
+[ 3] [Active ] [ 1] Bundle Repository (0.8.0)
+[ 4] [Installed ] [ 1] Simple (0.8.0)
+-> start 4
+Simple bundle 4 has started.
+From native: Hello!
+From embedded JAR: Hello!
+Entry: META-INF/
+Entry: org/
+Entry: libfoo.so
+The 'javax.servlet.http' package is not available.
+The 'javax.servlet' package is not available.
+->
+</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 Felix profile. 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="ApacheFelixUsageDocumentation-installingbundlesproxies"></a></p>
+
+<h3><a name="ApacheFelixUsageDocumentation-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<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>
+
+<p><a name="ApacheFelixUsageDocumentation-configuringfelix"></a></p>
+
+<h2><a name="ApacheFelixUsageDocumentation-ConfiguringFelix"></a>Configuring Felix</h2>
+<p>Felix uses properties to configure certain aspects of its behavior. When you execute Felix using <tt>bin/felix.jar</tt> there are two property files that are consulted, they are <tt>conf/system.properties</tt> and <tt>conf/config.properties</tt> in the Felix installation directory. Both files use standard Java property file syntax.</p>
+
+<p>The <tt>conf/system.properties</tt> file provides a convenient
+mechanism for defining Java system properties, but it is largely
+ignored by Felix, since Felix does not use system properties 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>
+<div class="preformatted"><div class="preformattedContent">
+<pre>java -Dfelix.system.properties=file:/home/rickhall/system.properties -jar bin/felix.jar
+</pre>
+</div></div>
+<p>When executing Felix, nearly 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>
+system property. It is necessary to use a system property here since
+Felix needs this value to start execution. As an example, the following
+command could be used to specify a custom location for the
+configuration properties file:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>java -Dfelix.config.properties=file:/home/rickhall/config.properties -jar bin/felix.jar
+</pre>
+</div></div>
+<p>In this example the configuration properties will be read from the
+specified URL. All remaining configuration properties should be defined
+in the <tt>config.properties</tt> file itself. All configuration properties are accessible at run time via <tt>BundleContext.getProperty()</tt>.</p>
+
+<p>Felix does provide one other way to specify configuration
+properties, but to do so you must manually instantiate an instance of
+Felix, rather than executing Felix' JAR file. When you create your own
+instance of Felix, it is possible to pass in precise configuration
+properties to the <tt>Felix.start()</tt> method. If this approach is used, then no property files are consulted.</p>
+
+<p>The following properties describes the purpose of each Felix configuration property:</p>
+<ul>
+ <li><tt>felix.log.level</tt> - An integer value indicating the
+degree of logging reported by the framework; a higher value results in
+more logging. 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>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>
+ <li><tt>felix.auto.start</tt> - Space-delimited list of bundle URLs to automatically install and start when Oscar 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>
+ <li><tt>felix.startlevel.framework</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 Felix should enable the URL Handlers service, which will result in calls to <tt>URL.setURLStreamHandlerFactory()</tt> and <tt>URLConnection.setContentHandlerFactory()</tt>. The default value is "<tt>true</tt>" to enable the URL Handlers service.</li>
+ <li><tt>felix.embedded.execution</tt> - Flag to indicate whether Felix is embedded into a host application; the default value is "<tt>false</tt>". If this flag is "<tt>true</tt>" then Felix will not call <tt>System.exit()</tt> upon termination.</li>
+ <li><tt>felix.strict.osgi</tt> - Flag to indicate whether Felix is running in strict OSGi mode; the default value is "<tt>true</tt>". If this flag is "<tt>false</tt>" it currently enables a single non-OSGi-compliant feature: persisting <tt>BundleActivator</tt>s that implement <tt>Serializable</tt>. This feature is not recommended since it is non-compliant.</li>
+ <li><tt>felix.cache.bufsize</tt>
+- Sets the buffer size to be used by the bundle cache when copying JAR
+files and input streams; the default value is 4096 bytes. 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>felix.cache.dir</tt>
+- Sets the directory to be used by the bundle cache as its cache
+directory. The cache directory is where all profile directories are
+stored and a profile directory is where a set of installed bundles are
+stored. By default, the cache directory is <tt>.felix</tt> in the user's home directory. If this property is specified, then its value will be used as the cache directory instead of <tt>.felix</tt>. This directory will be created if it does not exist.</li>
+ <li><tt>felix.cache.profile</tt>
+- Sets the profile name that will be used to create a profile directory
+inside of the bundle cache directory. The created directory will
+contain all installed bundles associated with the profile.</li>
+ <li><tt>felix.cache.profiledir</tt>
+- Sets the directory to use as the profile directory for the bundle
+cache; by default the profile name is used to create a directory in the
+<tt>.felix</tt> bundle cache directory (more precisely <tt>${felix.cache.dir}/${felix.cache.profile</tt>}). If the <tt>felix.cache.profiledir</tt>
+property is specified, then the cache directory and profile name
+properties are ignored since they are only used to calculate the
+profile directory. The specified value of the profile directory
+property is used directly as the directory to contain all cached
+bundles. This directory will be created if it does not exist.</li>
+</ul>
+
+
+<p>The Felix installation contains a default <tt>conf/config.properties</tt> file for automatically starting the shell-related bundles.</p>
+
+<p><a name="ApacheFelixUsageDocumentation-propertysubstitution"></a></p>
+
+<h3><a name="ApacheFelixUsageDocumentation-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>${<property></tt>} syntax, where <tt><property></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.</p>
+
+<p><a name="ApacheFelixUsageDocumentation-defaultshell"></a></p>
+
+<h3><a name="ApacheFelixUsageDocumentation-ChangingtheCommandShellUserInterface"></a>Changing the Command Shell User Interface</h3>
+<p>Felix' shell service supports multiple user interface
+implementations; the default shell user interface is text-based, but a
+simple graphical shell is also available. To change the default shell
+user interface, you must download the Shell GUI and Shell GUI Plugin
+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>
+<div class="preformatted"><div class="preformattedContent">
+<pre>felix.auto.start.1=file:bundle/shell.jar file:bundle/shelltui.jar \
+ file:bundle/bundlerepository.jar
+</pre>
+</div></div>
+<p>This property value instructs Felix to automatically start the shell
+service, the shell textual user interface, and the bundle repository. (<em>Note:
+The "\" character at the end of the above line indicates that the
+property value continues on the next line; it is also possible to
+specify the property value on one line.</em>) For the GUI-based shell user interface, the property value should look something like this:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>felix.auto.start.1=file:bundle/shell.jar file:bundle/bundlerepository.jar \
+ file:bundle/shellgui.jar file:bundle/shellplugin.jar
+</pre>
+</div></div>
+<p>This property value instructs Felix to automatically start the shell
+service, the bundle repository, the shell GUI, and the shell GUI
+plugins.</p>
+
+<p><a name="ApacheFelixUsageDocumentation-configuringbundles"></a></p>
+
+<h2><a name="ApacheFelixUsageDocumentation-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="#ApacheFelixUsageDocumentation-configuringfelix" title="configuring-felix on Apache Felix Usage Documentation">configuring Felix</a>.</p>
+
+<p><a name="ApacheFelixUsageDocumentation-feedback"></a></p>
+
+<h2><a name="ApacheFelixUsageDocumentation-Feedback"></a>Feedback</h2>
+
+<p>Subscribe to the Felix users mailing list by sending a message to <span class="nobr"><a href="mailto:users-subscribe@incubator.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>
+ </div>
+ </body></html>
\ No newline at end of file
diff --git a/main/doc/apache-felix-usage-documentation_files/apache.png b/main/doc/apache-felix-usage-documentation_files/apache.png
new file mode 100644
index 0000000..1bcce23
--- /dev/null
+++ b/main/doc/apache-felix-usage-documentation_files/apache.png
Binary files differ
diff --git a/main/doc/apache-felix-usage-documentation_files/felix_logo.png b/main/doc/apache-felix-usage-documentation_files/felix_logo.png
new file mode 100644
index 0000000..d653a06
--- /dev/null
+++ b/main/doc/apache-felix-usage-documentation_files/felix_logo.png
Binary files differ
diff --git a/main/doc/apache-felix-usage-documentation_files/mail_small.gif b/main/doc/apache-felix-usage-documentation_files/mail_small.gif
new file mode 100644
index 0000000..a3b7d9f
--- /dev/null
+++ b/main/doc/apache-felix-usage-documentation_files/mail_small.gif
Binary files differ
diff --git a/main/doc/apache-felix-usage-documentation_files/site.css b/main/doc/apache-felix-usage-documentation_files/site.css
new file mode 100644
index 0000000..d60ada8
--- /dev/null
+++ b/main/doc/apache-felix-usage-documentation_files/site.css
@@ -0,0 +1,21 @@
+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% }
+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: 0px; right: 0px; top: 0px; height: 107px; background: url(bg_header.png) repeat-x }
+.menu { position: absolute; top: 107px; left: 0px; width: 198px; bottom: 0px; padding: 0px; background-color: #fcfcfc }
+.menu ul { background-image: url(bg_menu.png); list-style: none; padding-left: 80px; margin-top: 0px; padding-top: 20px; padding-bottom: 20px; color: #4a4a43 }
+.menu a { text-decoration: none; color: #4a4a43 }
+.main { position: absolute; top: 107px; left: 220px; right: 80px }
+.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
diff --git a/main/doc/changelog.txt b/main/doc/changelog.txt
new file mode 100644
index 0000000..ed9e40a
--- /dev/null
+++ b/main/doc/changelog.txt
@@ -0,0 +1,20 @@
+Changes from 0.8.0-incubator to 1.0.0
+-------------------------------------
+
+* [2007-01-31] Changed how the system packages property is calculated to
+ make it more robust; previously it was leaving a dangling comma if the
+ execution platform was not known.
+* [2007-02-05] Added system package support for Java 6. (FELIX-201)
+* [2007-02-13] Removed support for trusted certificate authorities; this
+ will be added later as an extension.
+* [2007-03-16] Felix configuration properties can now be set as system
+ properties when using the standard launcher. (FELIX-250)
+* [2007-03-28] No longer including config.properties in the JAR file.
+* [2007-04-13] The javax.net and javax.net.ssl packages were missing
+ from the system packages properties.
+* [2007-04-13] Fixed a bug where the launcher was not correctly calculating
+ the installation directory correctly.
+* [2007-05-07] Was accidentally including OBR service interface package
+ in main JAR.
+* [2007-05-22] Now includes the Service Tracker package in main JAR.
+* [2007-07-04] Modified to use the new Felix embedding API.
