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 2018/10/09 13:36:06 UTC
svn commit: r1036192 - in /websites/staging/felix/trunk/content: ./
documentation/subprojects/apache-felix-dependency-manager/reference/
Author: buildbot
Date: Tue Oct 9 13:36:06 2018
New Revision: 1036192
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/reference/dependency-bundle.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-configuration.html
Propchange: websites/staging/felix/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Oct 9 13:36:06 2018
@@ -1 +1 @@
-1843269
+1843271
Modified: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-bundle.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-bundle.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-bundle.html Tue Oct 9 13:36:06 2018
@@ -88,40 +88,36 @@ h2:hover > .headerlink, h3:hover > .head
visibility: hidden;
}
h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
-<p>A bundle dependency allows you to depend on a bundle in a certain set of states, as indicated by a state mask. You can also use a filter condition that is matched against all manifest entries. Finally you can provide a reference to an existing bundle.</p>
-<h2 id="bundledependency">@BundleDependency<a class="headerlink" href="#bundledependency" title="Permanent link">¶</a></h2>
-<p>A bundle dependency allows you to depend on a bundle in a certain set of states (INSTALLED\|RESOLVED\|STARTED\|...), as indicated by a state mask. You can also use a filter condition that is matched against all manifest entries. When applied on a class field, optional unavailable dependencies are injected with a NullObject.</p>
-<p>Attributes:</p>
-<ul>
-<li><em>changed</em>: Returns the callback method to be invoked when the service have changed.</li>
-<li><em>removed</em>: Returns the callback method to invoke when the service is lost.</li>
-<li><em>required</em>: Returns whether the dependency is required or not.</li>
-<li><em>filter</em>: Returns the filter dependency</li>
-<li><em>stateMask</em>: Returns the bundle state mask (Bundle.INSTALLED \| Bundle.ACTIVE etc ...).</li>
-<li><em>propagate</em>: Specifies if the manifest headers from the bundle should be propagated to the service properties.</li>
-<li><em>name</em>: The name used when dynamically configuring this dependency from the init method. Specifying this attribute allows to dynamically configure the dependency filter and required flag from the Service's init method. All unnamed dependencies will be injected before the init() method; so from the init() method, you can then pick up whatever information needed from already injected (unnamed) dependencies, and configure dynamically your named dependencies, which will then be calculated once the init() method returns.
-Please refer to <a href="">Here</a>.</li>
-</ul>
-<h2 id="usage-examples">Usage Examples<a class="headerlink" href="#usage-examples" title="Permanent link">¶</a></h2>
-<p>In the following example, the "SCR" Component allows to track all bundles containing a specific "Service-Component" OSGi header, in order to load and manage all Declarative Service components specified in the SCR xml documents referenced by the header:</p>
-<div class="codehilite"><pre><span class="nd">@Component</span>
-<span class="kd">public</span> <span class="kd">class</span> <span class="nc">SCR</span> <span class="o">{</span>
- <span class="nd">@BundleDependency</span><span class="o">(</span><span class="n">required</span> <span class="o">=</span> <span class="kc">false</span><span class="o">,</span>
- <span class="n">removed</span> <span class="o">=</span> <span class="s">"unloadServiceComponents"</span><span class="o">,</span>
- <span class="n">filter</span> <span class="o">=</span> <span class="s">"(Service-Component=*)"</span>
- <span class="n">stateMask</span> <span class="o">=</span> <span class="n">Bundle</span><span class="o">.</span><span class="na">ACTIVE</span><span class="o">)</span>
- <span class="kt">void</span> <span class="nf">loadServiceComponents</span><span class="o">(</span><span class="n">Bundle</span> <span class="n">b</span><span class="o">)</span> <span class="o">{</span>
- <span class="n">String</span> <span class="n">descriptorPaths</span> <span class="o">=</span> <span class="o">(</span><span class="n">String</span><span class="o">)</span> <span class="n">b</span><span class="o">.</span><span class="na">getHeaders</span><span class="o">().</span><span class="na">get</span><span class="o">(</span><span class="s">"Service-Component"</span><span class="o">);</span>
- <span class="c1">// load all service component specified in the XML descriptorPaths files ...</span>
+<p>A bundle dependency allows you to depend on a bundle in a certain set of states, as indicated by a state mask.
+You can also use a filter condition that is matched against all manifest entries. Finally you can provide a
+reference to an existing bundle.</p>
+<p>To declare a bundle dependency, you need to use the createServiceDependency inherited from the DependencyActivatorBase, or available from the
+DependencyManager class.</p>
+<p>Here is an example of a component which tracks all ACTIVE bundles having a Service-Component header in the manifest:</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">Activator</span> <span class="kd">extends</span> <span class="n">DependencyActivatorBase</span> <span class="o">{</span>
+ <span class="nd">@Override</span>
+ <span class="kd">public</span> <span class="kt">void</span> <span class="nf">init</span><span class="o">(</span><span class="n">BundleContext</span> <span class="n">ctx</span><span class="o">,</span> <span class="n">DependencyManager</span> <span class="n">dm</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">Exception</span> <span class="o">{</span>
+ <span class="n">Component</span> <span class="n">scr</span> <span class="o">=</span> <span class="n">createComponent</span><span class="o">()</span>
+ <span class="o">.</span><span class="na">setImplementation</span><span class="o">(</span><span class="n">ScrRuntime</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
+ <span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="n">createBundleDependency</span><span class="o">().</span><span class="na">setFilter</span><span class="o">(</span><span class="s">"(Service-Component=*"</span><span class="o">).</span><span class="na">setStateMask</span><span class="o">(</span><span class="n">Bundle</span><span class="o">.</span><span class="na">ACTIVE</span><span class="o">).</span><span class="na">setCallbacks</span><span class="o">(</span><span class="s">"bind"</span><span class="o">,</span> <span class="s">"unbind"</span><span class="o">));</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">ScrRuntime</span> <span class="o">{</span>
+ <span class="kt">void</span> <span class="nf">bind</span><span class="o">(</span><span class="n">Bundle</span> <span class="n">bundle</span><span class="o">)</span> <span class="o">{</span>
+ <span class="c1">// load SCR descriptors from the starting bundle</span>
<span class="o">}</span>
- <span class="kt">void</span> <span class="nf">unloadServiceComponents</span><span class="o">(</span><span class="n">Bundle</span> <span class="n">b</span><span class="o">)</span> <span class="o">{</span>
- <span class="c1">// unload all service component we loaded from our "loadServiceComponents" method.</span>
+ <span class="kt">void</span> <span class="nf">unbind</span><span class="o">(</span><span class="n">Bundle</span> <span class="n">bundle</span><span class="o">)</span> <span class="o">{</span>
+ <span class="c1">// unload SCR descriptors from the starting bundle</span>
<span class="o">}</span>
<span class="o">}</span>
</pre></div>
+
+
+<p>The dependency is optional by default, and will invoke the ScrRuntime.bind callback each time a bundle containing some Declarative Service component is started.</p>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1665812 by marrs on Wed, 11 Mar 2015 09:02:04 +0000
+ Rev. 1843270 by pderop on Tue, 9 Oct 2018 13:35:41 +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/reference/dependency-configuration.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-configuration.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-configuration.html Tue Oct 9 13:36:06 2018
@@ -130,7 +130,7 @@ As proxies are injected, no implementati
<li>for arrays, collections and maps, an <em>empty</em> array/collection/map is returned;</li>
<li>for other interface types that are treated as configuration type a Null-object is returned. </li>
</ul>
-<p>Usage example where a component depends on a configuration:</p>
+<p>Here is a component depends on a configuration:</p>
<div class="codehilite"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">ServiceImpl</span> <span class="o">{</span>
<span class="kt">void</span> <span class="nf">updated</span><span class="o">(</span><span class="n">Dictionary</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">Object</span><span class="o">></span> <span class="n">cnf</span><span class="o">)</span> <span class="o">{</span>
<span class="k">if</span> <span class="o">(</span><span class="n">cnf</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span>
@@ -152,7 +152,8 @@ As proxies are injected, no implementati
</pre></div>
-<p>Here is the same example, but a custom configuration type interface is used (by default, the FQDN of the configuration type is assumed to be the configuration pid):</p>
+<p>Here is the same example, but a custom configuration type interface is used
+(by default, the FQDN of the configuration type is assumed to be the configuration pid):</p>
<div class="codehilite"><pre><span class="kd">public</span> <span class="kd">interface</span> <span class="nc">MyConfig</span> <span class="o">{</span>
<span class="n">String</span> <span class="nf">getAddress</span><span class="o">();</span>
<span class="kt">int</span> <span class="nf">getPort</span><span class="o">();</span>
@@ -177,71 +178,8 @@ As proxies are injected, no implementati
<span class="o">}</span>
<span class="o">}</span>
</pre></div>
-
-
-<h2 id="configurationdependency">@ConfigurationDependency<a class="headerlink" href="#configurationdependency" title="Permanent link">¶</a></h2>
-<p>Configuration dependencies can be defined usnig the @ConfigurationDependency.
-Annotation attributes:</p>
-<ul>
-<li><em>pid</em>: Returns the pid for a given service (by default, the pid is the service class name).</li>
-<li><em>propagate</em>: Returns true if the configuration properties must be published along with the service. Any additional service properties specified directly are merged with these.</li>
-</ul>
-<p>In the following example, the "Printer" component depends on a configuration with "org.apache.felix.sample.Printer" PID.</p>
-<div class="codehilite"><pre><span class="kn">package</span> <span class="n">org</span><span class="o">.</span><span class="na">apache</span><span class="o">.</span><span class="na">felix</span><span class="o">.</span><span class="na">sample</span><span class="o">;</span>
-
-<span class="nd">@Component</span>
-<span class="kd">public</span> <span class="kd">class</span> <span class="nc">Printer</span> <span class="o">{</span>
- <span class="nd">@ConfigurationDependency</span>
- <span class="kt">void</span> <span class="nf">updated</span><span class="o">(</span><span class="n">Dictionary</span> <span class="n">config</span><span class="o">)</span> <span class="o">{</span>
- <span class="c1">// load printer ip/port from the provided dictionary.</span>
- <span class="o">}</span>
-<span class="o">}</span>
-</pre></div>
-
-
-<p>This other example shows how to specify a configuration dependency, as well as meta data used to customize the
-WebConsole GUI. Using these meta data, you can specify for example the default value for your
-configurations data, some descriptions, the cardinality of configuration values, etc ...
-(we use here standard bnd metatype annotations, <a href="http://bnd.bndtools.org/chapters/210-metatype.html">see bnd metatype documentation here</a>.</p>
-<p>First, we define our PrinterConfiguration interface annotated with standard bndtools metatatype annotations:</p>
-<div class="codehilite"><pre> <span class="p">:::</span><span class="n">java</span>
- <span class="n">package</span> <span class="n">sample</span><span class="p">;</span>
- <span class="n">import</span> <span class="n">aQute</span><span class="p">.</span><span class="n">bnd</span><span class="p">.</span><span class="n">annotation</span><span class="p">.</span><span class="n">metatype</span><span class="p">.</span><span class="n">Meta</span><span class="p">.</span><span class="n">AD</span><span class="p">;</span>
- <span class="n">import</span> <span class="n">aQute</span><span class="p">.</span><span class="n">bnd</span><span class="p">.</span><span class="n">annotation</span><span class="p">.</span><span class="n">metatype</span><span class="p">.</span><span class="n">Meta</span><span class="p">.</span><span class="n">OCD</span><span class="p">;</span>
-
- <span class="p">@</span><span class="n">OCD</span><span class="p">(</span><span class="n">description</span> <span class="p">=</span> "<span class="n">Declare</span> <span class="n">here</span> <span class="n">the</span> <span class="n">Printer</span> <span class="n">Configuration</span><span class="p">.</span>"<span class="p">)</span>
- <span class="n">public</span> <span class="n">interface</span> <span class="n">PrinterConfiguration</span> <span class="p">{</span>
- <span class="p">@</span><span class="n">AD</span><span class="p">(</span><span class="n">description</span> <span class="p">=</span> "<span class="n">Enter</span> <span class="n">the</span> <span class="n">printer</span> <span class="n">ip</span> <span class="n">address</span>"<span class="p">)</span>
- <span class="n">String</span> <span class="n">ipAddress</span><span class="p">();</span>
-
- <span class="p">@</span><span class="n">AD</span><span class="p">(</span><span class="n">description</span> <span class="p">=</span> "<span class="n">Enter</span> <span class="n">the</span> <span class="n">printer</span> <span class="n">address</span> <span class="n">port</span> <span class="n">number</span><span class="p">.</span>"<span class="p">)</span>
- <span class="n">int</span> <span class="n">portNumber</span><span class="p">();</span>
- <span class="p">}</span>
-</pre></div>
-
-
-<p>Next, we define our Printer service with an <code>updated</code> method which is injected with the
-PrinterConfiguration type that is implemented by DM (all interface methods will lookup in the
-actual configuration dictionary).</p>
-<div class="codehilite"><pre> <span class="p">:::</span><span class="n">java</span>
- <span class="n">package</span> <span class="n">sample</span><span class="p">;</span>
- <span class="n">import</span> <span class="n">aQute</span><span class="p">.</span><span class="n">bnd</span><span class="p">.</span><span class="n">annotation</span><span class="p">.</span><span class="n">metatype</span><span class="o">.*</span><span class="p">;</span>
-
- <span class="p">@</span><span class="n">Component</span>
- <span class="n">public</span> <span class="n">class</span> <span class="n">Printer</span> <span class="p">{</span>
- <span class="p">@</span><span class="n">ConfigurationDependency</span> <span class="o">//</span> <span class="n">Will</span> <span class="n">use</span> <span class="n">pid</span> "<span class="n">sample</span><span class="p">.</span><span class="n">PrinterConfiguration</span>"
- <span class="n">void</span> <span class="n">updated</span><span class="p">(</span><span class="n">PrinterConfiguration</span> <span class="n">cnf</span><span class="p">)</span> <span class="p">{</span>
- <span class="k">if</span> <span class="p">(</span><span class="n">cnf</span> !<span class="p">=</span> <span class="n">null</span><span class="p">)</span> <span class="p">{</span>
- <span class="o">//</span> <span class="n">load</span> <span class="n">configuration</span> <span class="n">from</span> <span class="n">the</span> <span class="n">provided</span> <span class="n">dictionary</span><span class="p">,</span> <span class="n">or</span> <span class="n">throw</span> <span class="n">an</span> <span class="n">exception</span> <span class="n">of</span> <span class="n">any</span> <span class="n">configuration</span> <span class="n">error</span><span class="p">.</span>
- <span class="n">String</span> <span class="n">ip</span> <span class="p">=</span> <span class="n">cnf</span><span class="p">.</span><span class="n">ipAddress</span><span class="p">();</span>
- <span class="n">int</span> <span class="n">port</span> <span class="p">=</span> <span class="n">cnf</span><span class="p">.</span><span class="n">portNumber</span><span class="p">();</span>
- <span class="p">...</span>
- <span class="p">}</span>
- <span class="p">}</span>
- <span class="p">}</span>
-</pre></div>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1783995 by jawi on Wed, 22 Feb 2017 09:54:59 +0000
+ Rev. 1843271 by pderop on Tue, 9 Oct 2018 13:35:50 +0000
</div>
<div class="trademarkFooter">
Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project