Add framework distribution.
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@910114 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/main.distribution/doc/apache-felix-framework-launching-and-embedding.html b/main.distribution/doc/apache-felix-framework-launching-and-embedding.html
new file mode 100644
index 0000000..fc4887d
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-launching-and-embedding.html
@@ -0,0 +1,1067 @@
+<!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 Launching and Embedding</title>
+ <link rel="stylesheet" href="apache-felix-framework-launching-and-embedding_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-launching-and-embedding_files/logo.png" border="0"></a></div><div class="header"><a href="http://www.apache.org/"><img alt="Apache" src="apache-felix-framework-launching-and-embedding_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-launching-and-embedding_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="ApacheFelixFrameworkLaunchingandEmbedding-ApacheFelixFrameworkLaunchingandEmbedding"></a>Apache Felix Framework Launching and Embedding</h1>
+
+<p><em>[This document describes framework launching introduced in Felix
+2.0.0 and is incompatible with older versions of the Felix framework.]</em></p>
+
+<ul>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-introduction">Introduction</a></li>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-overview">API Overview</a>
+ <ul>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-creatingandconfiguring">Creating and Configuring the Framework Instance</a></li>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-startinginstance">Starting the Framework Instance</a></li>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-stoppinginstance">Stopping the Framework Instance</a></li>
+ </ul>
+ </li>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-launching">Launching Felix</a>
+ <ul>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-standardlauncher">Standard Felix Launcher</a></li>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-customlauncher">Custom Felix Launcher</a></li>
+ </ul>
+ </li>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-embedding">Embedding Felix</a>
+ <ul>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-hostinteraction">Host/Felix Interaction</a></li>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-hostservices">Providing Host Application Services</a></li>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-hostserviceusage">Using Services Provided by Bundles</a>
+ <ul>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-servicereflection">Using Bundle Services via Reflection</a></li>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-serviceother">Other Approaches</a></li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-caveat">Caveat</a></li>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-feedback">Feedback</a></li>
+</ul>
+
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-introduction"></a></p>
+
+<h1><a name="ApacheFelixFrameworkLaunchingandEmbedding-Introduction"></a>Introduction</h1>
+
+<p>The Apache Felix framework is intended to be easily launchable and
+embeddable. For example, Felix avoids the use of system properties for
+configuration, since these are globals and can cause interference if
+multiple framework instances are created in the same VM. Felix also
+tries 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="ApacheFelixFrameworkLaunchingandEmbedding-overview"></a></p>
+
+<h1><a name="ApacheFelixFrameworkLaunchingandEmbedding-APIOverview"></a>API Overview</h1>
+
+<p>The Felix framework is implemented by the <tt>org.apache.felix.framework.Felix</tt> class or just <tt>Felix</tt>
+for short. As part of the R4.2 OSGi specification, the launching and
+embedding API of the OSGi framework has been standardized. The approach
+is to have the framework implement the <tt>org.osgi.framework.launch.Framework</tt> interface, which extends the <tt>org.osgi.framework.Bundle</tt> interface. These interfaces provide the necessary means to launch and manage framework instances. The <tt>Bundle</tt> interface is defined as:</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> Bundle
+{
+ BundleContext getBundleContext();
+ <span class="code-object">long</span> getBundleId();
+ URL getEntry(<span class="code-object">String</span> name);
+ Enumeration getEntryPaths(<span class="code-object">String</span> path);
+ Enumeration findEntries(<span class="code-object">String</span> path, <span class="code-object">String</span> filePattern, <span class="code-object">boolean</span> recurse);
+ Dictionary getHeaders();
+ Dictionary getHeaders(<span class="code-object">String</span> locale);
+ <span class="code-object">long</span> getLastModified();
+ <span class="code-object">String</span> getLocation();
+ URL getResource(<span class="code-object">String</span> name);
+ Enumeration getResources(<span class="code-object">String</span> name) <span class="code-keyword">throws</span> IOException;
+ ServiceReference[] getRegisteredServices();
+ ServiceReference[] getServicesInUse();
+ <span class="code-object">int</span> getState();
+ <span class="code-object">String</span> getSymbolicName();
+ Version getVersion();
+ <span class="code-object">boolean</span> hasPermission(<span class="code-object">Object</span> obj);
+ <span class="code-object">Class</span> loadClass(<span class="code-object">String</span> name) <span class="code-keyword">throws</span> ClassNotFoundException;
+ void start() <span class="code-keyword">throws</span> BundleException;
+ void stop() <span class="code-keyword">throws</span> BundleException;
+ void uninstall() <span class="code-keyword">throws</span> BundleException;
+ void update() <span class="code-keyword">throws</span> BundleException;
+ void update(InputStream is) <span class="code-keyword">throws</span> BundleException;
+}
+</pre>
+</div></div>
+
+<p>The <tt>Framework</tt> interface is defined as:</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> Framework <span class="code-keyword">extends</span> Bundle
+{
+ void init();
+ FrameworkEvent waitForStop();
+}
+</pre>
+</div></div>
+
+<p>To actually construct a framework instance, the R4.2 specification defines the FrameworkFactory interface:</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> FrameworkFactory
+{
+ Framework newFramework(Map configMap);
+}
+</pre>
+</div></div>
+
+<p>The framework factory can be used to create configured framework instances. It is obtained following the standard <tt>META-INF/services</tt> approach.</p>
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-creatingandconfiguring"></a></p>
+
+<h2><a name="ApacheFelixFrameworkLaunchingandEmbedding-CreatingandConfiguringtheFrameworkInstance"></a>Creating and Configuring the Framework Instance</h2>
+
+<p>You use the framework factory to construct and configure a framework
+instance (or by directly instantiating the Felix class). The
+configuration map may contain the following OSGi standard properties:</p>
+
+<ul>
+ <li><tt>org.osgi.framework.system.packages</tt> - specifies a
+list of packages the system bundle should export from the environment;
+if this is not set, then the framework uses a reasonable default fault.</li>
+ <li><tt>org.osgi.framework.system.packages.extra</tt>
+- specifies a list of additional packages the system bundle should
+export from the environment that are appended to the packages specified
+in <tt>org.osgi.framework.system.packages</tt>; there is no default value for this property.</li>
+ <li><tt>org.osgi.framework.bootdelegation</tt>
+- specifies a list of packages that should be made implicitly available
+to all bundles from the environment (i.e., no need to import them);
+there is no default value for this property and its use should be
+avoided.</li>
+ <li><tt>org.osgi.framework.storage</tt> - specifies the
+path to a directory, which will be created if it does not exist, to use
+for bundle cache storage; the default value for this property is "<tt>felix-cache</tt>" in the current working directory.</li>
+ <li><tt>org.osgi.framework.storage.clean</tt>
+- specifies whether the bundle cache should be flushed; the default
+value for this property is "none", but it can be changed to
+"onFirstInit" to flush the bundle cache when the framework is
+initialized.</li>
+ <li><tt>org.osgi.framework.startlevel.beginning</tt> - specifies the start level the framework enters upon startup; the default value for this property is 1.</li>
+</ul>
+
+
+<p>Felix also has the following, non-standard configuration properties:</p>
+
+<ul>
+ <li><tt>felix.cache.rootdir</tt> - specifies which directory should be used to calculate absolute paths when relative paths are used for the <tt>org.osgi.framework.storage</tt> property; the default value for this property is the current working directory.</li>
+ <li><tt>felix.systembundle.activators</tt> - specifies 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.</li>
+ <li><tt>felix.log.logger</tt> - specifies an instance of <tt>org.apache.felix.framework.util.Logger</tt> that the framework uses as its default logger.</li>
+ <li><tt>felix.log.level</tt> - specifies an integer <tt>String</tt>
+whose value indicates the degree of logging reported by the framework;
+the default value is "1" and "0" turns off logging completely,
+otherwise log levels match those specified in the OSGi Log Service
+(i.e., 1 = error, 2 = warning, 3 = information, and 4 = debug).</li>
+ <li><tt>felix.startlevel.bundle</tt> - specifies the start level for newly installed bundles; the default value is 1.</li>
+ <li><tt>felix.bootdelegation.implicit</tt>
+- specifies whether or not the framework should try to guess when to
+boot delegate when external code tries to load classes or resources;
+the default value is "<tt>true</tt>".</li>
+ <li><tt>framework.service.urlhandlers</tt> - specifies whether or not to activate the URL Handlers service for the framework instance; the default value is "<tt>true</tt>", which results in the <tt>URL.setURLStreamHandlerFactory()</tt> and <tt>URLConnection.setContentHandlerFactory()</tt> being called.</li>
+</ul>
+
+
+<p>The configuration map is copied and the keys are treated as case
+insensitive. You are not able to change the framework's configuration
+after construction. If you need a different configuration, you must
+create a new framework instance.</p>
+
+<div class="panelMacro"><table class="warningMacro"><colgroup><col width="24"><col></colgroup><tbody><tr><td valign="top"><img src="apache-felix-framework-launching-and-embedding_files/forbidden.gif" alt="" align="absmiddle" border="0" height="16" width="16"></td><td><b>WARNING</b><br><p>Felix configuration properties have change considerably starting from <tt>1.4.0</tt>; if you are upgrading from an earlier version, the <a href="http://felix.apache.org/site/apache-felix-framework-usage-documentation.html#ApacheFelixFrameworkUsageDocumentation-migrating">usage document</a> describes the configuration property changes.</p></td></tr></tbody></table></div>
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-startinginstance"></a></p>
+
+<h2><a name="ApacheFelixFrameworkLaunchingandEmbedding-StartingtheFrameworkInstance"></a>Starting the Framework Instance</h2>
+
+<p>The <tt>start()</tt> method is used to start the framework instance. If the <tt>init()</tt> method was not invoked prior to calling <tt>start()</tt>, then it is invoked by <tt>start()</tt>. The two methods result in two different framework state transitions:</p>
+
+<ul>
+ <li><tt>init()</tt> results in the framework instance in the <tt>Bundle.STARTING</tt> state.</li>
+ <li><tt>start()</tt> results in the framework instance in the <tt>Bundle.ACTIVE</tt> state.</li>
+</ul>
+
+
+<p>The <tt>init()</tt> method is necessary since the framework does not have a <tt>BundleContext</tt> when it is first created, so a transition to the <tt>Bundle.STARTING</tt> state is required to acquire its context (via <tt>Bundle.getBundleContext()</tt>) for performing various tasks, such as installing bundles. Note that Felix also provides the <tt>felix.systembundle.activators</tt> property that serves a similar purpose, but is not standard. After the <tt>init()</tt> method completes, the follow actions have been performed:</p>
+
+<ul>
+ <li>Event handling is enabled.</li>
+ <li>The security manager is installed if it is enabled.</li>
+ <li>The framework is set to start level 0.</li>
+ <li>All bundles in the bundle caches are reified and their state is set to <tt>Bundle.INSTALLED</tt>.</li>
+ <li>The framework gets a valid <tt>BundleContext</tt>.</li>
+ <li>All framework-provided services are made available (e.g., PackageAdmin, StartLevel, etc.).</li>
+ <li>The framework enters the <tt>Bundle.STARTING</tt> state.</li>
+</ul>
+
+
+<p>A call to <tt>start()</tt> is necessary to start the framework instance, if the <tt>init()</tt> method is invoked manually. Invoking <tt>init()</tt> or <tt>start()</tt> on an already started framework as no effect.</p>
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-stoppinginstance"></a></p>
+
+<h2><a name="ApacheFelixFrameworkLaunchingandEmbedding-StoppingtheFrameworkInstance"></a>Stopping the Framework Instance</h2>
+
+<p>To stop the framework instance, invoke the <tt>stop()</tt> method, which will asynchronously stop the framework. To know when the framework has finished its shutdown sequence, use the <tt>waitForStop()</tt> method to wait until it is complete. A stopped framework will be in the <tt>Bundle.RESOLVED</tt> state. It is possible to restart the framework, using the normal combination of <tt>init()</tt>/<tt>start()</tt> methods as previously described.</p>
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-launching"></a></p>
+
+<h1><a name="ApacheFelixFrameworkLaunchingandEmbedding-LaunchingaFramework"></a>Launching a Framework</h1>
+
+<p>Launching a framework is fairly simple and involves only four steps:</p>
+
+<ol>
+ <li>Define some configuration properties.</li>
+ <li>Obtain framework factory.</li>
+ <li>Use factory to create framework with the configuration properties.</li>
+ <li>Invoke the <tt>Framework.start()</tt> method.</li>
+</ol>
+
+
+<p>In reality, the first step is optional, since all properties will
+have reasonable defaults, but if you are creating a launcher you will
+generally want to more than that, such as automatically installing and
+starting bundles when you start the framework instance. The default
+Felix launcher defines reusable functionality to automatically install
+and/or start bundles upon framework startup; see the <a href="http://felix.apache.org/site/apache-felix-framework-usage-documentation.html#ApacheFelixFrameworkUsageDocumentation-configuringfelix">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="ApacheFelixFrameworkLaunchingandEmbedding-standardlauncher"></a></p>
+
+<h2><a name="ApacheFelixFrameworkLaunchingandEmbedding-StandardFelixFrameworkLauncher"></a>Standard Felix Framework 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 panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">public</span> <span class="code-keyword">static</span> void main(<span class="code-object">String</span>[] args) <span class="code-keyword">throws</span> Exception
+{
+ <span class="code-comment">// (1) Check <span class="code-keyword">for</span> command line arguments and verify usage.
+</span> <span class="code-object">String</span> bundleDir = <span class="code-keyword">null</span>;
+ <span class="code-object">String</span> cacheDir = <span class="code-keyword">null</span>;
+ <span class="code-object">boolean</span> expectBundleDir = <span class="code-keyword">false</span>;
+ <span class="code-keyword">for</span> (<span class="code-object">int</span> i = 0; i < args.length; i++)
+ {
+ <span class="code-keyword">if</span> (args[i].equals(BUNDLE_DIR_SWITCH))
+ {
+ expectBundleDir = <span class="code-keyword">true</span>;
+ }
+ <span class="code-keyword">else</span> <span class="code-keyword">if</span> (expectBundleDir)
+ {
+ bundleDir = args[i];
+ expectBundleDir = <span class="code-keyword">false</span>;
+ }
+ <span class="code-keyword">else</span>
+ {
+ cacheDir = args[i];
+ }
+ }
+ <span class="code-keyword">if</span> ((args.length > 3) || (expectBundleDir && bundleDir == <span class="code-keyword">null</span>))
+ {
+ <span class="code-object">System</span>.out.println(<span class="code-quote">"Usage: [-b <bundle-deploy-dir>] [<bundle-cache-dir>]"</span>);
+ <span class="code-object">System</span>.exit(0);
+ }
+
+ <span class="code-comment">// (2) Load system properties.
+</span> Main.loadSystemProperties();
+
+ <span class="code-comment">// (3) Read configuration properties.
+</span> Properties configProps = Main.loadConfigProperties();
+ <span class="code-keyword">if</span> (configProps == <span class="code-keyword">null</span>)
+ {
+ <span class="code-object">System</span>.err.println(<span class="code-quote">"No "</span> + CONFIG_PROPERTIES_FILE_VALUE + <span class="code-quote">" found."</span>);
+ configProps = <span class="code-keyword">new</span> Properties();
+ }
+
+ <span class="code-comment">// (4) Copy framework properties from the system properties.
+</span> Main.copySystemProperties(configProps);
+
+ <span class="code-comment">// (5) Use the specified auto-deploy directory over <span class="code-keyword">default</span>.
+</span> <span class="code-keyword">if</span> (bundleDir != <span class="code-keyword">null</span>)
+ {
+ configProps.setProperty(AutoProcessor.AUTO_DEPLOY_DIR_PROPERY, bundleDir);
+ }
+
+ <span class="code-comment">// (6) Use the specified bundle cache directory over <span class="code-keyword">default</span>.
+</span> <span class="code-keyword">if</span> (cacheDir != <span class="code-keyword">null</span>)
+ {
+ configProps.setProperty(Constants.FRAMEWORK_STORAGE, cacheDir);
+ }
+
+ <span class="code-comment">// (7) Add a shutdown hook to clean stop the framework.
+</span> <span class="code-object">String</span> enableHook = configProps.getProperty(SHUTDOWN_HOOK_PROP);
+ <span class="code-keyword">if</span> ((enableHook == <span class="code-keyword">null</span>) || !enableHook.equalsIgnoreCase(<span class="code-quote">"<span class="code-keyword">false</span>"</span>))
+ {
+ <span class="code-object">Runtime</span>.getRuntime().addShutdownHook(<span class="code-keyword">new</span> <span class="code-object">Thread</span>() {
+ <span class="code-keyword">public</span> void run()
+ {
+ <span class="code-keyword">try</span>
+ {
+ <span class="code-keyword">if</span> (m_fwk != <span class="code-keyword">null</span>)
+ {
+ m_fwk.stop();
+ m_fwk.waitForStop(0);
+ }
+ }
+ <span class="code-keyword">catch</span> (Exception ex)
+ {
+ <span class="code-object">System</span>.err.println(<span class="code-quote">"Error stopping framework: "</span> + ex);
+ }
+ }
+ });
+ }
+
+ <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-keyword">try</span>
+ {
+ <span class="code-comment">// (8) Create an instance and initialize the framework.
+</span> FrameworkFactory factory = getFrameworkFactory();
+ m_fwk = factory.newFramework(configProps);
+ m_fwk.init();
+ <span class="code-comment">// (9) Use the system bundle context to process the auto-deploy
+</span> <span class="code-comment">// and auto-install/auto-start properties.
+</span> AutoProcessor.process(configProps, m_fwk.getBundleContext());
+ <span class="code-comment">// (10) Start the framework.
+</span> m_fwk.start();
+ <span class="code-comment">// (11) Wait <span class="code-keyword">for</span> framework to stop to exit the VM.
+</span> m_fwk.waitForStop(0);
+ <span class="code-object">System</span>.exit(0);
+ }
+ <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>The launcher supports setting the auto-deploy directory (with the <tt>-b</tt>
+switch) and setting the bundle cache path with a single argument, so
+check for this and issue a usage message it there are more than one
+arguments.</li>
+ <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 are copied into the set of
+configuration properties. This provide an easy way to add to or
+override configuration properties specified in the <tt>config.properties</tt> file, since the Felix instance will never look at system properties for configuration.</li>
+ <li>If the <tt>-b</tt> switch was used to specify an auto-deploy directory, then use that to set the value of <tt>felix.auto.deploy.dir</tt>.</li>
+ <li>If a single command-line argument is specified, then use that to set the value of <tt>org.osgi.framework.storage</tt>; relative paths are relative to the current directory unless the <tt>felix.cache.rootdir</tt> property is set.</li>
+ <li>Add a shutdown hook to cleanly stop the framework, unless the hook is disabled.</li>
+ <li>Create a framework instance using the <tt>FrameworkFactory</tt> passing in the configuration properties, then initialize the factory instance; see the <a href="#ApacheFelixFrameworkLaunchingandEmbedding-customlauncher">custom launcher example</a> below to see how the META-INF/services <tt>FrameworkFactory</tt> is obtained.</li>
+ <li>Use <tt>org.apache.felix.main.AutoProcessor</tt>, which will automatically deploy any bundles in the auto-deploy directory as well as bundles specified in the <tt>felix.auto.install</tt> and <tt>felix.auto.start</tt>
+configuration properties during framework startup to automatically
+install and/or start bundles; see the usage document for more
+information <a href="http://felix.apache.org/site/apache-felix-framework-usage-documentation.html#ApacheFelixFrameworkUsageDocumentation-configuringframework">configuration properties</a> and <a href="http://felix.apache.org/site/apache-felix-framework-usage-documentation.html#ApacheFelixFrameworkUsageDocumentation-autodeploy">bundle auto-deploy</a>.</li>
+ <li>Invoke <tt>waitForStop()</tt> to wait for the framework to stop to force the VM to exit; this is necessary because the framework never calls <tt>System.exit()</tt> and some libraries (e.g., Swing) create threads that will not allow the VM to exit.</li>
+</ol>
+
+
+<p>The framework is not active until the <tt>start()</tt> method is
+called. If no shell bundles are installed and started or if there is
+difficulty locating the shell bundles specified in the auto-start
+property, 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="ApacheFelixFrameworkLaunchingandEmbedding-customlauncher"></a></p>
+
+<h2><a name="ApacheFelixFrameworkLaunchingandEmbedding-CustomFrameworkLauncher"></a>Custom Framework 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 panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>launcher/
+ lib/
+ org.apache.felix.main-2.0.0.jar
+ bundle/
+ org.apache.felix.shell-1.4.0.jar
+ org.apache.felix.shell.tui-1.4.0.jar
+ src/
+ example/
+ Main.java
+</pre>
+</div></div>
+
+<p>The <tt>lib/</tt> directory contains Felix' main JAR file, which
+also contains the OSGi core interfaces. The main JAR file is used so
+that we can reuse the default launcher's auto-install/auto-start
+configuration property handling; if these capabilities are not needed,
+then it would be possible to use the framework JAR file instead of the
+main JAR file. 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 panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">package</span> example;
+
+<span class="code-keyword">import</span> java.io.*;
+<span class="code-keyword">import</span> org.osgi.framework.launch.*;
+<span class="code-keyword">import</span> org.apache.felix.main.AutoProcessor;
+
+<span class="code-keyword">public</span> class Main
+{
+ <span class="code-keyword">private</span> <span class="code-keyword">static</span> Framework m_fwk = <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>);
+
+ <span class="code-keyword">try</span>
+ {
+ m_fwk = getFrameworkFactory().newFramework(<span class="code-keyword">null</span>);
+ m_fwk.init()
+ AutoProcessor.process(<span class="code-keyword">null</span>, m_fwk.getBundleContext());
+ m_fwk.start();
+ m_fwk.waitForStop();
+ <span class="code-object">System</span>.exit(0);
+ }
+ <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);
+ }
+ }
+
+ <span class="code-keyword">private</span> <span class="code-keyword">static</span> FrameworkFactory getFrameworkFactory() <span class="code-keyword">throws</span> Exception
+ {
+ URL url = Main.class.getClassLoader().getResource(
+ <span class="code-quote">"META-INF/services/org.osgi.framework.launch.FrameworkFactory"</span>);
+ <span class="code-keyword">if</span> (url != <span class="code-keyword">null</span>)
+ {
+ BufferedReader br = <span class="code-keyword">new</span> BufferedReader(<span class="code-keyword">new</span> InputStreamReader(url.openStream()));
+ <span class="code-keyword">try</span>
+ {
+ <span class="code-keyword">for</span> (<span class="code-object">String</span> s = br.readLine(); s != <span class="code-keyword">null</span>; s = br.readLine())
+ {
+ s = s.trim();
+ <span class="code-comment">// Try to load first non-empty, non-commented line.
+</span> <span class="code-keyword">if</span> ((s.length() > 0) && (s.charAt(0) != '#'))
+ {
+ <span class="code-keyword">return</span> (FrameworkFactory) <span class="code-object">Class</span>.forName(s).newInstance();
+ }
+ }
+ }
+ <span class="code-keyword">finally</span>
+ {
+ <span class="code-keyword">if</span> (br != <span class="code-keyword">null</span>) br.close();
+ }
+ }
+
+ <span class="code-keyword">throw</span> <span class="code-keyword">new</span> Exception(<span class="code-quote">"Could not find framework factory."</span>);
+ }
+}
+</pre>
+</div></div>
+
+<p>This launcher relies on the default behavior of <tt>AutoProcessor</tt>
+to automatically deploy the shell bundles. This simple, generic
+launcher provides a good starting point if the default Felix launcher
+is not sufficient. Since very few configuration properties are
+specified, the default values are used. For the bundle auto-deploy
+directory, "<tt>bundle</tt>" in the current directory is used, while for the framework bundle cache, "<tt>felix-cache</tt>" in the current directory is used.</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 panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"> m_fwk = getFrameworkFactory().newFramework(<span class="code-keyword">null</span>);
+ m_fwk.init()
+</pre>
+</div></div>
+
+<p>These steps get a the framework factory service and use it to create
+a framework instance with a default configuration. Once the framework
+instance is created, it is initialized with <tt>init()</tt>.</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"> AutoProcessor.process(<span class="code-keyword">null</span>, m_fwk.getBundleContext());
+</pre>
+</div></div>
+
+<p>The <tt>AutorProcessor</tt> will automatically deploy bundles in the
+auto-deploy directory and any referenced from the auto-install/start
+properties. Since we are using an empty configuration, the auto-deploy
+directory is the <tt>bundle</tt> directory in the current directory
+and there are no auto properties. Therefore, in this case, the two
+shell bundles will be installed.</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"> m_fwk.start();
+ m_fwk.waitForStop();
+ <span class="code-object">System</span>.exit(0);
+</pre>
+</div></div>
+
+<p>These final steps start the framework and cause the launching
+application thread to wait for the framework to stop and when it does
+the launching thread calls <tt>System.exit()</tt> to make sure the VM actually exits.</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"> <span class="code-keyword">private</span> <span class="code-keyword">static</span> FrameworkFactory getFrameworkFactory() <span class="code-keyword">throws</span> Exception
+ {
+ ...
+ }
+</pre>
+</div></div>
+
+<p>This method retrieves the framework factory service by doing a
+META-INF/services resource lookup, which it can use to obtain the
+concrete class name for the factory. If you are using Java 6, then you
+can use the <tt>ServiceLoader</tt> API in the JRE to further simplify the factory service lookup.</p>
+
+<p>The following command compiles the launcher when run from the root directory of the launcher project:</p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>javac -d . -classpath lib/org.apache.felix.main-2.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 panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>java -cp .:lib/org.apache.felix.main-2.0.0.jar example.Main
+</pre>
+</div></div>
+
+<p>After executing this command, a "<tt>felix-cache/</tt>" directory is created that contains the cached bundles, which were installed from the <tt>bundle/</tt> directory.</p>
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-embedding"></a></p>
+
+<h1><a name="ApacheFelixFrameworkLaunchingandEmbedding-EmbeddingFelix"></a>Embedding Felix</h1>
+
+<p>Embedding Felix into a host application is a simple way to provide a
+sophisticated extensibility mechanism (i.e., a 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="ApacheFelixFrameworkLaunchingandEmbedding-hostinteraction"></a></p>
+
+<h2><a name="ApacheFelixFrameworkLaunchingandEmbedding-Host/FelixInteraction"></a>Host/Felix Interaction</h2>
+
+<p>In the section on <a href="#ApacheFelixFrameworkLaunchingandEmbedding-launching">launching</a> Felix above, the <tt>Felix</tt> accepts a configuration property called <tt>felix.systembundle.activators</tt>,
+which is a list of bundle activator instances. These bundle activator
+instances provide a convenient way for host applications to interact
+with the Felix framework. The ability offered by these activators can
+also be accomplished by invoking <tt>init()</tt> on the framework instance and the using <tt>getBundleContext()</tt> to get the System Bundle's context, but it can be more convenient to use an activator instance.</p>
+
+<p>Each activator instance passed into the constructor effectively becomes part of the System Bundle. This means that the <tt>start()</tt>/<tt>stop()</tt> methods of each activator instance in the list gets invoked when the System Bundle's activator <tt>start()</tt>/<tt>stop()</tt> methods gets invoked, respectively. Each activator instance will be given the System Bundle's <tt>BundleContext</tt> object so that they can interact with the framework. Consider following snippet of a bundle activator:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<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 panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<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 configuration property map.
+</span> Map configMap = <span class="code-keyword">new</span> HashMap();
+ <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);
+ configMap.put(FelixConstants.SYSTEMBUNDLE_ACTIVATORS_PROP, list);
+
+ <span class="code-keyword">try</span>
+ {
+ <span class="code-comment">// Now create an instance of the framework with
+</span> <span class="code-comment">// our configuration properties.
+</span> m_felix = <span class="code-keyword">new</span> Felix(configMap);
+ <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.stop();
+ m_felix.waitForStop();
+ }
+}
+</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="ApacheFelixFrameworkLaunchingandEmbedding-hostservices"></a></p>
+
+<h2><a name="ApacheFelixFrameworkLaunchingandEmbedding-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="#ApacheFelixFrameworkLaunchingandEmbedding-hostinteraction">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.extra</tt> configuration property previously presented.</p>
+
+<p>Consider the follow simple property lookup service:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<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 panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<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 panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<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.osgi.framework.Constants;
+
+<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 configuration property map.
+</span> Map configMap = <span class="code-keyword">new</span> HashMap();
+ <span class="code-comment">// Export the host provided service <span class="code-keyword">interface</span> <span class="code-keyword">package</span>.
+</span> configMap.put(Constants.FRAMEWORK_SYSTEMPACKAGES_EXTRA,
+ <span class="code-quote">"host.service.lookup; version=1.0.0"</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);
+ configMap.put(FelixConstants.SYSTEMBUNDLE_ACTIVATORS_PROP, list);
+
+ <span class="code-keyword">try</span>
+ {
+ <span class="code-comment">// Now create an instance of the framework with
+</span> <span class="code-comment">// our configuration properties.
+</span> m_felix = <span class="code-keyword">new</span> Felix(configMap);
+ <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.stop();
+ m_felix.waitForStop();
+ }
+}
+</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="ApacheFelixFrameworkLaunchingandEmbedding-hostserviceusage"></a></p>
+
+<h2><a name="ApacheFelixFrameworkLaunchingandEmbedding-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.extra</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 panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<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 panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<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 use command
+services provided by bundles installed inside its embedded Felix
+framework instance. The following code snippet illustrates one possible
+approach:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<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.cache.BundleCache;
+<span class="code-keyword">import</span> org.osgi.framework.Constants;
+<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 configuration property map.
+</span> Map configMap = <span class="code-keyword">new</span> HashMap();
+ <span class="code-comment">// Export the host provided service <span class="code-keyword">interface</span> <span class="code-keyword">package</span>.
+</span> configMap.put(Constants.FRAMEWORK_SYSTEMPACKAGES_EXTRA,
+ <span class="code-quote">"host.service.command; version=1.0.0"</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);
+ configMap.put(FelixConstants.SYSTEMBUNDLE_ACTIVATORS_PROP, list);
+
+ <span class="code-keyword">try</span>
+ {
+ <span class="code-comment">// Now create an instance of the framework with
+</span> <span class="code-comment">// our configuration properties.
+</span> m_felix = <span class="code-keyword">new</span> Felix(configMap);
+ <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.stop();
+ m_felix.waitForStop();
+ }
+}
+</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.</p>
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-servicereflection"></a></p>
+
+<h3><a name="ApacheFelixFrameworkLaunchingandEmbedding-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="ApacheFelixFrameworkLaunchingandEmbedding-serviceother"></a></p>
+
+<h3><a name="ApacheFelixFrameworkLaunchingandEmbedding-OtherApproaches"></a>Other Approaches</h3>
+
+<p>The <a href="http://code.google.com/p/transloader/" rel="nofollow">Transloader</a> project is another attempt at dealing with issues of classes loaded from different class loaders and may be of interest.</p>
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-caveat"></a></p>
+
+<h1><a name="ApacheFelixFrameworkLaunchingandEmbedding-Caveat"></a>Caveat</h1>
+
+<p>The code in this document has not been thoroughly tested nor 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>
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-feedback"></a></p>
+
+<h2><a name="ApacheFelixFrameworkLaunchingandEmbedding-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>