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/04 21:00:12 UTC
svn commit: r942354 - in /websites/staging/felix/trunk/content: ./
documentation/subprojects/apache-felix-dependency-manager-4/reference/components.html
documentation/subprojects/apache-felix-dependency-manager-4/reference/dependencies.html
Author: buildbot
Date: Wed Mar 4 20:00:11 2015
New Revision: 942354
Log:
Staging update by buildbot for felix
Modified:
websites/staging/felix/trunk/content/ (props changed)
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/components.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/dependencies.html
Propchange: websites/staging/felix/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed Mar 4 20:00:11 2015
@@ -1 +1 @@
-1664113
+1664129
Modified: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/components.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/components.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/components.html Wed Mar 4 20:00:11 2015
@@ -69,19 +69,35 @@
<h1>Apache Felix Dependency Manager - Components</h1>
<p>Components are declared by the dependency manager and can be implemented by POJOs that contain no references to the OSGi framework whatsoever. Components are the main building blocks of your OSGi application. They have a life cycle, can register themselves as services and have zero or more dependencies.</p>
+<p>You can either use the Java API or the Java Annotations and this reference section describes both.</p>
+<h1 id="types-of-components">Types of Components</h1>
+<p>There are different types of Dependency Manager components:</p>
+<ul>
+<li><a href="component-singleton.html"><em>Component</em></a>: Components are the main building blocks for OSGi applications. They can publish themselves as a service, and/or they can have dependencies. These dependencies will influence their life cycle as component will only be activated when all required dependencies are available.</li>
+<li><a href="component-singleton.html"><em>Aspect Service</em></a>: A service that provides a non-functional aspect on top of an existing service. In aspect oriented programming, an aspect, or interceptor can sit between a client and another target service used by the client. An Aspect Service first tracks a target service and is created once the target service is detected. Then the Aspect Service is provided, but with a higher ranking, and the client is transparently updated with the aspect. Aspects can be chained and may apply to the same target service (and in this case, the ranking of the Aspect service is used to chain aspects in the proper order).</li>
+<li><a href="component-singleton.html"><em>Adapter Service</em></a>: A Service that adapts another existing service into a new one. Like with aspects, sometimes you want to create adapters for certain services, which add certain behavior that results in the publication of (in this case) a different service. Adapters can dynamically be added and removed and allow you to keep your basic services implementations clean and simple, adding extra features on top of them in a modular way.</li>
+<li><a href="component-singleton.html"><em>Bundle Adapter Service</em></a>: creates an OSGi service a service on top of a given bundle.</li>
+<li><a href="component-singleton.html"><em>Resource Adapter Service</em></a>: creates an OSGi service on top of a specific Resource.</li>
+<li><a href="component-singleton.html"><em>Factory Configuration Adapter Service</em></a>: creates an OSGi service from ConfigAdmin, using a factoryPid, and a ManagedServiceFactory.</li>
+</ul>
+<h1 id="component">Component</h1>
<h2 id="life-cycle">Life cycle</h2>
<p>The dependency manager, as part of a bundle, shares the generic bundle life cycle explained in the OSGi specification. The life cycle of the dependency manager itself, and the components it manages, can be located inside the <em>active</em> state of the hosting bundle.</p>
<p>Each component you define gets its own life cycle, which is explained in the state diagram below.</p>
-<p>{gliffy:name=state-diagram|align=center|size=L|version=2}</p>
+<p>TODO {gliffy:name=state-diagram|align=center|size=L|version=2}</p>
<p>A component is associated with an instance. This instance can either be specified directly, or you can specify its class. If you do the latter, the actual instance will be created lazily. </p>
-<p>Changes in the state of the component will trigger the following life cycle methods:
-<em> <code>init</code>,
-</em> <code>start</code>,
-<em> <code>stop</code> and
-</em> <code>destroy</code>.</p>
-<p>The dependency manager will look for methods with these names and one of the following signatures in this order:
-<em> (Component),
-</em> ().</p>
+<p>Changes in the state of the component will trigger the following life cycle methods:</p>
+<ul>
+<li><code>init</code>, </li>
+<li><code>start</code>, </li>
+<li><code>stop</code> and </li>
+<li><code>destroy</code>.</li>
+</ul>
+<p>The dependency manager will look for methods with these names and one of the following signatures in this order:</p>
+<ul>
+<li>(Component),</li>
+<li>().</li>
+</ul>
<p>If you don't specify anything, the methods with these names will be invoked on the instance. By using <code>setCallbacks()</code> you can however change this behavior: You can change the names of the methods to look for. Any methods that are set to <code>null</code> will not be invoked at all. Another thing you can do is to specify a different instance to invoke these methods on. If you do that, you will usually want to use the first signature, which gives you a reference to the <code>Component</code> whose life cycle method was invoked.</p>
<h2 id="interfaces-and-properties">Interfaces and properties</h2>
<p>Components in the context of the dependency manager can be published as OSGi services under one or more interface names, plus optionally a set of properties. This is no different than a normal OSGi service. It's important to mention that you don't have to register a service. If you don't, you basically created a component that can do work and have dependencies and a managed life cycle.</p>
@@ -90,16 +106,7 @@
<h2 id="factories">Factories</h2>
<p>Out of the box, there already is support for lazy instantiation, meaning that the dependency manager can create component instances for you when their required dependencies are resolved. However, sometimes creating a single instance using a default constructor is not enough. In those cases, you can tell the dependency manager to delegate the creation process to a factory.</p>
<h1 id="annotations">Annotations</h1>
-<p>This page describes the different types of Dependency Manager components:</p>
-<ul>
-<li><em>Component</em>: Components are the main building blocks for OSGi applications. They can publish themselves as a service, and/or they can have dependencies. These dependencies will influence their life cycle as component will only be activated when all required dependencies are available.</li>
-<li><em>Aspect Service</em>: A service that provides a non-functional aspect on top of an existing service. In aspect oriented programming, an aspect, or interceptor can sit between a client and another target service used by the client. An Aspect Service first tracks a target service and is created once the target service is detected. Then the Aspect Service is provided, but with a higher ranking, and the client is transparently updated with the aspect. Aspects can be chained and may apply to the same target service (and in this case, the ranking of the Aspect service is used to chain aspects in the proper order).</li>
-<li><em>Adapter Service</em>: A Service that adapts another existing service into a new one. Like with aspects, sometimes you want to create adapters for certain services, which add certain behavior that results in the publication of (in this case) a different service. Adapters can dynamically be added and removed and allow you to keep your basic services implementations clean and simple, adding extra features on top of them in a modular way.</li>
-<li><em>Bundle Adapter Service</em>: creates an OSGi service a service on top of a given bundle.</li>
-<li><em>Resource Adapter Service</em>: creates an OSGi service on top of a specific Resource.</li>
-<li><em>Factory Configuration Adapter Service</em>: creates an OSGi service from ConfigAdmin, using a factoryPid, and a ManagedServiceFactory.</li>
-</ul>
-<h2 id="component">@Component</h2>
+<h2 id="component_1">@Component</h2>
<p>This annotation annotates an implementation class that optionally publishes
an OSGi service, and optionally has some dependencies, with a managed
lifecycle. </p>
@@ -182,9 +189,9 @@ factory that instantiated this component
be also updated with all public properties (which don't start with a dot).</p>
<p>Usage example:</p>
<div class="codehilite"><pre><span class="cm">/**</span>
-<span class="cm"> * This component will be activated once the bundle is started and when all required dependencies</span>
-<span class="cm"> * are available.</span>
-<span class="cm"> */</span>
+<span class="cm"> * This component will be activated once the bundle is started and when all required dependencies</span>
+<span class="cm"> * are available.</span>
+<span class="cm"> */</span>
<span class="nd">@Component</span>
<span class="kd">class</span> <span class="nc">X</span> <span class="kd">implements</span> <span class="n">Z</span> <span class="o">{</span>
<span class="nd">@ConfigurationDependency</span><span class="o">(</span><span class="n">pid</span><span class="o">=</span><span class="s">"MyPid"</span><span class="o">)</span>
@@ -208,9 +215,11 @@ be also updated with all public properti
<div class="codehilite"><pre> <span class="nd">@Component</span><span class="o">(</span><span class="n">factorySet</span><span class="o">=</span><span class="s">"MyComponentFactory"</span><span class="o">,</span> <span class="n">factoryConfigure</span><span class="o">=</span><span class="s">"configure"</span><span class="o">)</span>
<span class="kd">class</span> <span class="nc">X</span> <span class="kd">implements</span> <span class="n">Z</span> <span class="o">{</span>
<span class="kt">void</span> <span class="nf">configure</span><span class="o">(</span><span class="n">Dictionary</span> <span class="n">conf</span><span class="o">)</span> <span class="o">{</span>
- <span class="c1">// Configure or reconfigure our component. The conf is provided by the factory,</span>
- <span class="c1">// and all public properties (which don't start with a dot) are propagated with the</span>
- <span class="c1">// Service properties eventually specified in the properties annotation attribute.</span>
+ <span class="c1">// Configure or reconfigure our component. The conf is provided by </span>
+ <span class="c1">// the factory, and all public properties (which don't</span>
+ <span class="c1">// start with a dot) are propagated with the Service</span>
+ <span class="c1">// properties eventually specified in the properties</span>
+ <span class="c1">// annotation attribute.</span>
<span class="o">}</span>
<span class="nd">@ServiceDependency</span>
@@ -220,7 +229,8 @@ be also updated with all public properti
<span class="nd">@Start</span>
<span class="kt">void</span> <span class="nf">start</span><span class="o">()</span> <span class="o">{</span>
- <span class="c1">// Our component is starting and is about to be registered in the OSGi registry as a Z service.</span>
+ <span class="c1">// Our component is starting and is about to be registered</span>
+ <span class="c1">// in the OSGi registry as a Z service.</span>
<span class="o">}</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">doService</span><span class="o">()</span> <span class="o">{</span>
@@ -228,13 +238,14 @@ be also updated with all public properti
<span class="o">}</span>
<span class="o">}</span>
-<span class="cm">/**</span>
+ <span class="cm">/**</span>
<span class="cm"> * This class will instantiate some X component instances</span>
<span class="cm"> */</span>
-<span class="nd">@Component</span>
-<span class="kd">class</span> <span class="nc">Y</span> <span class="o">{</span>
+ <span class="nd">@Component</span>
+ <span class="kd">class</span> <span class="nc">Y</span> <span class="o">{</span>
+ <span class="c1">// This Set acts as a Factory API for creating X component instances.</span>
<span class="nd">@ServiceDependency</span><span class="o">(</span><span class="n">filter</span><span class="o">=</span><span class="s">"(dm.factory.name=MyComponentFactory)"</span><span class="o">)</span>
- <span class="n">Set</span><span class="o"><</span><span class="n">Dictionary</span><span class="o">></span> <span class="n">_XFactory</span><span class="o">;</span> <span class="c1">// This Set acts as a Factory API for creating X component instances.</span>
+ <span class="n">Set</span><span class="o"><</span><span class="n">Dictionary</span><span class="o">></span> <span class="n">_XFactory</span><span class="o">;</span>
<span class="nd">@Start</span>
<span class="kt">void</span> <span class="nf">start</span><span class="o">()</span> <span class="o">{</span>
@@ -250,14 +261,15 @@ be also updated with all public properti
<span class="n">x1</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"foo"</span><span class="o">,</span> <span class="s">"bar1_modified"</span><span class="o">);</span>
<span class="n">_XFactory</span><span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="n">x1</span><span class="o">);</span>
- <span class="c1">// Destroy all components (Notice that invoking _XFactory.clear() also destroys every X instances)</span>
+ <span class="c1">// Destroy all components (Notice that invoking</span>
+ <span class="c1">// _XFactory.clear() also destroys every X instances)</span>
<span class="n">_XFactory</span><span class="o">.</span><span class="na">remove</span><span class="o">(</span><span class="n">x1</span><span class="o">);</span>
<span class="n">_XFactory</span><span class="o">.</span><span class="na">remove</span><span class="o">(</span><span class="n">x2</span><span class="o">);</span>
<span class="o">}</span>
<span class="o">}</span>
</pre></div>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1664040 by marrs on Wed, 4 Mar 2015 15:21:58 +0000
+ Rev. 1664129 by marrs on Wed, 4 Mar 2015 19:59:46 +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-4/reference/dependencies.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/dependencies.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/dependencies.html Wed Mar 4 20:00:11 2015
@@ -68,20 +68,27 @@
<h1></h1>
- <h3 id="dependencies">Dependencies</h3>
+ <h1 id="dependencies">Dependencies</h1>
<p>The dependency manager supports many different types of dependencies, all of which can be required or optional. A dependency can be added to one or more components and it is possible to add them dynamically (even from within the component itself if necessary, which allows for some really dynamic dependency configuration).</p>
-<h4 id="injection">Injection</h4>
+<h2 id="injection">Injection</h2>
<p>One way to deal with dependencies is to have them injected into your component instances automatically. All you need to do is simply declare a field of the same type as your dependency, make the member volatile so any changes will become visible immediately and you're done. If a dependency is optional, a null object will be injected if the dependency is not available.</p>
<p>Sometimes you need more control over injection, so optionally you can even specify the name of the field to inject into. This allows you to depend on different dependencies of the same type, or simply to prevent injection into more than one field.</p>
-<h4 id="callbacks">Callbacks</h4>
+<h2 id="callbacks">Callbacks</h2>
<p>When keeping track of multiple instances of a dependency, or when you simply want something to happen whenever a dependency becomes (un)available or changes, you can define callbacks, like <code>added</code>, <code>changed</code> and <code>removed</code>. Optionally, you can provide the dependency manager with an instance to invoke these callback methods on. If you don't, they'll be invoked on the component instance.</p>
-<h4 id="types-of-dependencies">Types of Dependencies</h4>
-<p>Out of the box, several types of dependencies are supported: service, bundle, configuration, resource and temporal service. However, it's quite easy to add your own custom type of dependency too.</p>
-<h5 id="implementing-your-own-dependency">Implementing Your Own Dependency</h5>
+<h2 id="types-of-dependencies">Types of Dependencies</h2>
+<p>Out of the box, several types of dependencies are supported:</p>
+<ul>
+<li><a href="dependency-service.html">Service</a></li>
+<li><a href="dependency-configuration.html">Configuration</a></li>
+<li><a href="dependency-bundle.html">Bundle</a></li>
+<li><a href="dependency-resource.html">Resource</a></li>
+</ul>
+<p>However, it's quite easy to add your own custom type of dependency too, as is described below.</p>
+<h2 id="implementing-your-own-dependency">Implementing Your Own Dependency</h2>
<p>All dependencies share a common API which you can implement yourself if you need a special type of dependency. Whilst not entirely trivial, this allows you to create your own types of dependencies. This can be useful for various scenarios where you want to have components that depend on things that are not services, bundles or configuration.</p>
<p>An example implementation can be found in one of the many test cases for the dependency manager: <code>CustomDependencyTest</code>. This implements a dependency that can be made available and unavailable by manipulating a <code>Toggle</code> which can be made available or unavailable. You basically have to implement two interfaces: <code>Dependency</code> and <code>DependencyActivation</code>. The former contains the bulk of the methods that you will need to implement and depending on the actual features you want your dependency to support, you have to implement some or all of them. The JavaDoc for each method plus the example code should get you started. The latter contains a couple of life cycle methods to start and stop tracking your custom dependency.</p>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1664040 by marrs on Wed, 4 Mar 2015 15:21:58 +0000
+ Rev. 1664129 by marrs on Wed, 4 Mar 2015 19:59:46 +0000
</div>
<div class="trademarkFooter">
Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project