You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@felix.apache.org by bu...@apache.org on 2015/03/11 10:07:26 UTC
svn commit: r943315 [2/2] - in /websites/staging/felix/trunk/content: ./
documentation/subprojects/
documentation/subprojects/apache-felix-dependency-manager/guides/
documentation/subprojects/apache-felix-dependency-manager/reference/
documentation/sub...
Modified: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/thread-model.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/thread-model.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/thread-model.html Wed Mar 11 09:07:25 2015
@@ -62,14 +62,14 @@
<div class="main">
<div class="breadcrump" style="font-size: 80%;">
- <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/subprojects.html">Apache Felix Subproject Documentation</a> » <a href="/documentation/subprojects/apache-felix-dependency-manager.html">Dependency Manager 4</a>
+ <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/subprojects.html">Apache Felix Subproject Documentation</a> » <a href="/documentation/subprojects/apache-felix-dependency-manager.html">Apache Felix Dependency Manager</a>
</div>
<h1>Dependency Manager - Thread Model</h1>
<p>This section gives a brief overview of the default thread model used by Dependency Manager, and also explains how to start and handle components concurrently.</p>
-<h1 id="default-thread-model">Default thread model</h1>
+<h2 id="default-thread-model">Default thread model</h2>
<p>By default, Dependency Manager uses a lock-free/single thread model:</p>
<ul>
<li>When an external event that influence the state of a Component is taking place (for example, when a service dependency on which the Component is depending on is registered in the
@@ -86,7 +86,7 @@ then a job (J2) for this new event is ju
<p>This mechanism allows to serially handle all Component events (service dependencies) in FIFO order without maintaining any locks.</p>
<p>The following diagram illustrates the thread model we just described:</p>
<p><img src="./diagrams/serial-queue.png" alt="Serial Queue" style="width: 600px"/></p>
-<h1 id="enabling-parallelism-with-a-componentexecutorfactory">Enabling parallelism with a <em>ComponentExecutorFactory</em></h1>
+<h2 id="enabling-parallelism-with-a-componentexecutorfactory">Enabling parallelism with a <em>ComponentExecutorFactory</em></h2>
<p>As described above, all the external events that influence the state of a given component are handed by jobs scheduled in the Serial Queue of the Component, and the jobs are getting
executed serially by a single "master" thread. So usually, bundles are started from a single thread, meaning that all Components are then activated synchronously.</p>
<p>But when you register in the OSGi service registry a ComponentExecutorFactory, that factory will be used by DependencyManager to create an Executor of your choice for each Component,
@@ -102,7 +102,7 @@ is registered (In this way, it is not ne
<p>Some class name prefixes can also be negated (using "!"), in order to exclude some components from the list of components using the ComponentExecutorFactory service.</p>
<p>Notice that if the ComponentExecutorFactory itself and all its dependent services are defined using the Dependency Manager API, then you have to list the package of such components with a
"!" prefix, in order to indicate that those components must not wait for a ComponentExecutorFactory service (since they are part of the ComponentExecutorFactory implementation !). </p>
-<h2 id="examples-usage-of-the-orgapachefelixdependencymanagerparallel-property">Examples usage of the <em>org.apache.felix.dependencymanager.parallel</em> property:</h2>
+<h3 id="examples-usage-of-the-orgapachefelixdependencymanagerparallel-property">Examples usage of the <em>org.apache.felix.dependencymanager.parallel</em> property:</h3>
<div class="codehilite"><pre><span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">felix</span><span class="p">.</span><span class="n">dependencymanager</span><span class="p">.</span><span class="n">parallel</span><span class="p">=</span><span class="o">*</span>
<span class="o">-></span> <span class="n">means</span> <span class="n">all</span> <span class="n">components</span> <span class="n">must</span> <span class="n">be</span> <span class="n">cached</span> <span class="n">until</span> <span class="n">a</span> <span class="n">ComponentExecutorFactory</span> <span class="n">comes</span> <span class="n">up</span><span class="p">.</span>
@@ -117,7 +117,7 @@ is registered (In this way, it is not ne
</pre></div>
-<h2 id="examples-of-a-componentexecutorfactory-that-provides-a-shared-threadpool">Examples of a ComponentExecutorFactory that provides a shared threadpool:</h2>
+<h3 id="examples-of-a-componentexecutorfactory-that-provides-a-shared-threadpool">Examples of a ComponentExecutorFactory that provides a shared threadpool:</h3>
<p>First, we define the OSGi bundle context system property to enable parallelism for all DM Components excepts the one which declares the ComponentExecutorFactory:</p>
<div class="codehilite"><pre><span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">felix</span><span class="p">.</span><span class="n">dependencymanager</span><span class="p">.</span><span class="n">parallel</span><span class="p">=</span>!<span class="n">com</span><span class="p">.</span><span class="n">acme</span><span class="p">.</span><span class="n">management</span><span class="p">.</span><span class="n">threadpool</span><span class="p">,</span> <span class="o">*</span>
</pre></div>
@@ -164,7 +164,7 @@ is registered (In this way, it is not ne
<li><a href="https://svn.apache.org/repos/asf/felix/trunk/dependencymanager/org.apache.felix.dependencymanager.samples/src/org/apache/felix/dependencymanager/samples/tpool/">see the executor factory</a> sample code and README file to up-to-date informations.</li>
</ul>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1665703 by marrs on Tue, 10 Mar 2015 21:21:26 +0000
+ Rev. 1665812 by marrs on Wed, 11 Mar 2015 09:02:04 +0000
</div>
<div class="trademarkFooter">
Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project
Modified: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/tutorials/getting-started.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/tutorials/getting-started.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/tutorials/getting-started.html Wed Mar 11 09:07:25 2015
@@ -62,14 +62,13 @@
<div class="main">
<div class="breadcrump" style="font-size: 80%;">
- <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/subprojects.html">Apache Felix Subproject Documentation</a> » <a href="/documentation/subprojects/apache-felix-dependency-manager.html">Dependency Manager 4</a>
+ <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/subprojects.html">Apache Felix Subproject Documentation</a> » <a href="/documentation/subprojects/apache-felix-dependency-manager.html">Apache Felix Dependency Manager</a>
</div>
<h1>Dependency Manager - Getting Started</h1>
- <h2 id="getting-started">Getting Started</h2>
-<p>When developing an OSGi bundle that has dependencies and possibly registers services, there are two classes in particular we need to implement:</p>
+ <p>When developing an OSGi bundle that has dependencies and possibly registers services, there are two classes in particular we need to implement:</p>
<ol>
<li>The bundle activator which controls the life-cycle of the bundle.</li>
<li>The actual component, which can be a POJO.</li>
@@ -77,7 +76,7 @@
<p>When using the dependency manager, your bundle activator is a subclass of <code>DependencyActivatorBase</code>. It needs to implement the <code>init</code> life cycle method and can optionally also implement a <code>destroy</code> method. Both methods take two arguments: <code>BundleContext</code> and <code>DependencyManager</code>. The latter is your interface to the declarative API you can use to define your components and dependencies.</p>
<p>The following paragraphs will show various examples that explain how to do this. Subsequently, some more advanced scenarios will be covered that involve listening to dependency and component state changes and interacting with the OSGi framework from within your component implementation.</p>
<p>To use the dependency manager, you should put the <code>org.apache.felix.dependencymanager.jar</code> in your classpath while compiling and in your OSGi framework when running.</p>
-<h3 id="registering-a-service">Registering a service</h3>
+<h2 id="registering-a-service">Registering a service</h2>
<p>The first example is about registering a service. We extend <code>DependencyActivatorBase</code> and in the <code>init</code> method we use the reference to the <code>DependencyManager</code> to create and add a component. For this component we subsequently set its service interface and implementation. In this case the interface is the <code>Store</code> interface, the second parameter, <code>null</code>, allows you to provide properties along with the service registration. For the implementation, we only mention the <code>Class</code> of the implementation, which means the dependency manager will lazily instantiate it. In this case, there is not much point in doing that because the component has no dependencies, but if it had, the instantiation would only happen when those dependencies were resolved.</p>
<p>Notice that the dependency manager API uses method chaining to create a more or less "fluent" API that, with proper indentation, is very easy to read.</p>
<div class="codehilite"><pre><span class="n">public</span> <span class="n">class</span> <span class="n">Activator</span> <span class="n">extends</span> <span class="n">DependencyActivatorBase</span> <span class="p">{</span>
@@ -114,7 +113,7 @@
</pre></div>
-<h3 id="depending-on-a-service">Depending on a service</h3>
+<h2 id="depending-on-a-service">Depending on a service</h2>
<p>Our second example is that of a component that depends on two other services: our <code>Store</code> from the previous example and the standard OSGi <code>LogService</code>. Looking at the code, there is a small but important difference between the two: <code>Store</code> is a required dependency and <code>LogService</code> is not. This means that our component really needs a store to work, but if there is no logging available, it can work without. Also note that this component has no <code>setInterface</code> method, which simply means it is not itself a service. This is perfectly fine.</p>
<div class="codehilite"><pre><span class="n">public</span> <span class="n">class</span> <span class="n">Activator</span> <span class="n">extends</span> <span class="n">DependencyActivatorBase</span> <span class="p">{</span>
<span class="n">public</span> <span class="n">void</span> <span class="n">init</span><span class="p">(</span><span class="n">BundleContext</span> <span class="n">context</span><span class="p">,</span> <span class="n">DependencyManager</span> <span class="n">manager</span><span class="p">)</span> <span class="n">throws</span> <span class="n">Exception</span> <span class="p">{</span>
@@ -150,7 +149,7 @@
</pre></div>
-<h3 id="tracking-services-with-callbacks">Tracking services with callbacks</h3>
+<h2 id="tracking-services-with-callbacks">Tracking services with callbacks</h2>
<p>Sometimes, simply injecting services does not give you enough control over a dependency because you might want to track more than one, or you might want to execute some code on changes. For all those cases, callbacks are your friends. Since one of our goals is to not introduce any kind of API in our POJO, callbacks are declared by specifying their method names instead of through some interface. In this case, we have a dependency on <code>Translator</code> services, and we define <code>added</code> and <code>removed</code> as callbacks.</p>
<div class="codehilite"><pre><span class="n">public</span> <span class="n">class</span> <span class="n">Activator</span> <span class="n">extends</span> <span class="n">DependencyActivatorBase</span> <span class="p">{</span>
<span class="n">public</span> <span class="n">void</span> <span class="n">init</span><span class="p">(</span><span class="n">BundleContext</span> <span class="n">context</span><span class="p">,</span> <span class="n">DependencyManager</span> <span class="n">manager</span><span class="p">)</span> <span class="n">throws</span> <span class="n">Exception</span> <span class="p">{</span>
@@ -199,7 +198,7 @@
</pre></div>
-<h3 id="depending-on-a-configuration">Depending on a configuration</h3>
+<h2 id="depending-on-a-configuration">Depending on a configuration</h2>
<p>Not all dependencies are on services. There are several other types of dependencies that are supported, one of them is the configuration dependency. In fact, only <em>required</em> configuration dependencies are supported, because optional ones can just be achieved by registering as a <code>ManagedService</code> yourself. When defining the dependency, you must define the persistent ID of the service. The component will not become active until the configuration you depend on is available <em>and</em> is valid. The latter can be checked by your implementation as we will see below.</p>
<div class="codehilite"><pre><span class="n">public</span> <span class="n">class</span> <span class="n">Activator</span> <span class="n">extends</span> <span class="n">DependencyActivatorBase</span> <span class="p">{</span>
<span class="n">public</span> <span class="n">void</span> <span class="n">init</span><span class="p">(</span><span class="n">BundleContext</span> <span class="n">context</span><span class="p">,</span> <span class="n">DependencyManager</span> <span class="n">manager</span><span class="p">)</span> <span class="n">throws</span> <span class="n">Exception</span> <span class="p">{</span>
@@ -233,7 +232,7 @@
<span class="p">}</span>
</pre></div>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1665705 by marrs on Tue, 10 Mar 2015 21:24:23 +0000
+ Rev. 1665812 by marrs on Wed, 11 Mar 2015 09:02:04 +0000
</div>
<div class="trademarkFooter">
Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project
Modified: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/tutorials/leveraging-the-shell.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/tutorials/leveraging-the-shell.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/tutorials/leveraging-the-shell.html Wed Mar 11 09:07:25 2015
@@ -62,14 +62,13 @@
<div class="main">
<div class="breadcrump" style="font-size: 80%;">
- <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/subprojects.html">Apache Felix Subproject Documentation</a> » <a href="/documentation/subprojects/apache-felix-dependency-manager.html">Dependency Manager 4</a>
+ <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/subprojects.html">Apache Felix Subproject Documentation</a> » <a href="/documentation/subprojects/apache-felix-dependency-manager.html">Apache Felix Dependency Manager</a>
</div>
<h1>Dependency Manager - Leveraging the shell</h1>
- <h1 id="introduction">Introduction</h1>
-<p>The shell bundle for the dependency manager extends the gogo shell with one new command called "dm". This command can be used to get insight in the actual components and services in a running OSGi framework.</p>
+ <p>The shell bundle for the dependency manager extends the gogo shell with one new command called "dm". This command can be used to get insight in the actual components and services in a running OSGi framework.</p>
<p>Typing help <code>help dm</code> in the gogo shell gives an overview of the available command options.</p>
<div class="codehilite"><pre><span class="n">dm</span> <span class="o">-</span> <span class="n">List</span> <span class="n">dependency</span> <span class="n">manager</span> <span class="n">components</span>
<span class="n">scope</span><span class="p">:</span> <span class="n">dependencymanager</span>
@@ -97,7 +96,7 @@
</pre></div>
-<h1 id="usage-examples">Usage examples</h1>
+<h2 id="usage-examples">Usage examples</h2>
<p>Below are some examples for typical usage of the dependency manager shell commands. The examples are based on a simple component model with a dashboard which has a required dependency on four probes (temperature, humidity, radiation, pressure). The radiation probe requires a Sensor service but this sensor is not available.</p>
<p><strong>List all dependency manager components</strong></p>
<p><code>dm</code></p>
@@ -157,7 +156,7 @@ The following service(s) are missing:
<p><code>wtf</code> gives the root cause for components not being registered and therefore their services not being available. In a typical application components have dependencies on services implemented by components that have dependencies on services etcetera. This transitivity means that an entire chain of components could be unregistered due to a (few) root dependencies not being satisfied. <code>wtf</code> is about discovering those dependencies.</p>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1665705 by marrs on Tue, 10 Mar 2015 21:24:23 +0000
+ Rev. 1665812 by marrs on Wed, 11 Mar 2015 09:02:04 +0000
</div>
<div class="trademarkFooter">
Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project