| <!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> |
