felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r942314 [2/2] - in /websites/staging/felix/trunk/content: ./ documentation/subprojects/ documentation/subprojects/apache-felix-dependency-manager-4/guides/ documentation/subprojects/apache-felix-dependency-manager-4/reference/
Date Wed, 04 Mar 2015 15:22:30 GMT
Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/component-factory-configuration-adapter.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/component-factory-configuration-adapter.html (added)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/component-factory-configuration-adapter.html Wed Mar  4 15:22:29 2015
@@ -0,0 +1,318 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE- 2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+  <head>
+    <title>Apache Felix - </title>
+    <link rel="icon" href="/res/favicon.ico">
+    <link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
+    <link rel="stylesheet" href="/res/codehilite.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/">
+          <img border="0" alt="Apache Felix" src="/res/logo.png">
+        </a>
+      </div>
+      <div class="header">
+        <a href="http://www.apache.org/">
+          <img border="0" alt="Apache" src="/res/apache.png">
+        </a>
+      </div>
+    </div>
+    
+    <div class="menu"> 
+      <p><a href="/news.html">news</a>  <br />
+<a href="/license.html">license</a>  <br />
+<a href="/downloads.cgi">downloads</a>  <br />
+<a href="/documentation.html">documentation</a>  <br />
+<a href="/mailinglists.html">mailing lists</a>  <br />
+<a href="/documentation/community/contributing.html">contributing</a>  <br />
+<a href="/sitemap.html">site map</a>  <br />
+<a href="http://www.apache.org/">asf</a>  <br />
+<a href="http://www.apache.org/security/">security</a>  <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">sponsorship</a>  <br />
+<a href="http://www.apache.org/foundation/thanks.html">sponsors</a>    </p>
+<iframe
+    src="http://www.apache.org/ads/button.html"
+    style="border-width:0; float: left"
+    frameborder="0"
+    scrolling="no"
+    width="135"
+    height="135">
+</iframe>
+    </div>
+    
+    <div class="main">
+      <div class="breadcrump" style="font-size: 80%;">
+        <a href="/">Home</a>&nbsp;&raquo&nbsp;<a href="/documentation.html">Documentation</a>&nbsp;&raquo&nbsp;<a href="/documentation/subprojects.html">Apache Felix Subproject Documentation</a>&nbsp;&raquo&nbsp;<a href="/documentation/subprojects/apache-felix-dependency-manager-4.html">Apache Felix Dependency Manager 4</a>
+      </div>
+
+      
+      
+      <h1></h1>
+      <h2 id="factoryconfigurationadapterservice">@FactoryConfigurationAdapterService</h2>
+<p>Annotates a class that acts as a Factory Configuration Adapter Service. 
+For each new Config Admin factory configuration matching the specified 
+factoryPid, an instance of this service will be created. The adapter will be 
+registered with the specified interface, and with the specified adapter 
+service properties. Depending on the propagate parameter, every public 
+factory configuration properties (which don't start with ".") will be 
+propagated along with the adapter service properties.</p>
+<p>Like in @ConfigurationDependency, you can optionally specify the meta types of 
+your configurations for Web Console GUI customization (configuration 
+heading/descriptions/default values/etc ...). </p>
+<h3 id="annotation-attributes">Annotation attributes:</h3>
+<hr />
+<p><strong><code>provides</code></strong>  <br />
+<em>Required</em>: False  <br />
+<em>Default</em>: all directly implemented interfaces.
+The interface(s) to use when registering adapters. By default, directly implemented interfaces will be registered in the OSGi registry. </p>
+<hr />
+<p><strong><code>properties</code></strong>  <br />
+<em>Required</em>: False  <br />
+<em>Default</em>: --</p>
+<p>Adapter Service properties. Notice that public factory configuration is also 
+registered in service properties, (only if propagate is true). 
+Public factory configuration properties are those which don't starts with a 
+dot (".").</p>
+<hr />
+<p><strong><code>factoryPid</code></strong>  <br />
+<em>Required</em>: False  <br />
+<em>Default</em>: The class name, including the package.</p>
+<p>Returns the factory pid whose configurations will instantiate the 
+annotated service class. 
+(By default, the pid is the service class name). </p>
+<hr />
+<p><strong><code>updated</code></strong>  <br />
+<em>Required</em>: False  <br />
+<em>Default</em>: "updated"</p>
+<p>The Update method to invoke (defaulting to "updated"), when a factory 
+configuration is created or updated </p>
+<hr />
+<p><strong><code>propagate</code></strong>  <br />
+<em>Required</em>: False  <br />
+<em>Default</em>: false</p>
+<p>Returns true if the configuration properties must be published 
+along with the service. Any additional service properties specified directly 
+are merged with these. </p>
+<hr />
+<p><strong><code>heading</code></strong>  <br />
+<em>Required</em>: False  <br />
+<em>Default</em>: --</p>
+<p>The label used to display the tab name (or section) where the properties are 
+displayed. Example: "Printer Service". </p>
+<hr />
+<p><strong><code>description</code></strong>  <br />
+<em>Required</em>: False  <br />
+<em>Default</em>: --</p>
+<p>A human readable description of the PID this annotation is associated with. 
+Example: "Configuration for the PrinterService bundle". </p>
+<hr />
+<p><strong><code>factoryMethod</code></strong>  <br />
+<em>Required</em>: False  <br />
+<em>Default</em>: --</p>
+<p>Sets the static method used to create the adapter instance.</p>
+<hr />
+<p><strong><code>metadata</code></strong>  <br />
+<em>Required</em>: False  <br />
+<em>Default</em>: --
+An array of "PropertyMetaData annotations, specifying property types used to 
+expose properties in web console</p>
+<h3 id="propertymetadata-anotation-attributes">PropertyMetaData anotation attributes:</h3>
+<hr />
+<p><strong><code>description</code></strong>  <br />
+<em>Required</em>: True  <br />
+<em>Default</em>: --
+Returns the property description. The description may be localized and must 
+describe the semantics of this type and any constraints. 
+Example: "Select the log level for the Printer Service".</p>
+<hr />
+<p><strong><code>type</code></strong>  <br />
+<em>Required</em>: False  <br />
+<em>Default</em>: String</p>
+<p>Return the property primitive type (java.lang.String.class by default). 
+If must be either one of the following types:</p>
+<ul>
+<li>String.class</li>
+<li>Long.class</li>
+<li>Integer.class</li>
+<li>Character.class</li>
+<li>Byte.class</li>
+<li>Double.class</li>
+<li>Float.class</li>
+<li>Boolean.class</li>
+</ul>
+<hr />
+<p><strong><code>defaults</code></strong>  <br />
+<em>Required</em>: False  <br />
+<em>Default</em>: --</p>
+<p>Return a default for this property. The object must be of the appropriate 
+type as defined by the cardinality and getType(). The return type is a list of 
+String objects that can be converted to the appropriate type. 
+The cardinality of the return array must follow the absolute cardinality of
+this type. E.g. if the cardinality = 0, the array must contain 1 element. If 
+the cardinality is 1, it must contain 0 or 1 elements. If it is -5, it must 
+contain from 0 to max 5 elements. Note that the special case of a 0 
+cardinality, meaning a single value, does not allow arrays or vectors of 0 
+elements. </p>
+<hr />
+<p><strong><code>cardinality</code></strong>  <br />
+<em>Required</em>: False  <br />
+<em>Default</em>: --</p>
+<p>Returns the cardinality of this property (0 by default). The OSGi environment
+handles multi valued properties in arrays or in Vector objects. 
+The return value is defined as follows:</p>
+<ul>
+<li>x = Integer.MIN_VALUE:  no limit, but use Vector</li>
+<li>x &lt; 0: -x = max occurrences, store in Vector</li>
+<li>x &gt; 0: x = max occurrences, store in array <a href=""></a></li>
+<li>x = Integer.MAX_VALUE: no limit, but use array <a href=""></a></li>
+<li>x = 0: 1 occurrence required</li>
+</ul>
+<hr />
+<p><strong><code>required</code></strong>  <br />
+<em>Required</em>: False  <br />
+<em>Default</em>: true</p>
+<p>Tells if this property is required or not. </p>
+<hr />
+<p><strong><code>optionLabels</code></strong>  <br />
+<em>Required</em>: False  <br />
+<em>Default</em>: --</p>
+<p>Return a list of valid option labels for this property. The purpose of this 
+method is to allow menus with localized labels. It is associated with the 
+<em>optionValues</em> attribute. The labels returned here are ordered in the same 
+way as the <em>optionValues</em> attribute values. </p>
+<hr />
+<p><strong><code>optionValues</code></strong>  <br />
+<em>Required</em>: False  <br />
+<em>Default</em>: --</p>
+<p>Return a list of option values that this property can take. This list must be 
+in the same sequence as the <em>optionLabels</em> attribute. </p>
+<h3 id="usage-examples">Usage Examples</h3>
+<p>Here, a "Dictionary" service instance is instantiated for each existing 
+factory configuration instances matching the "DictionaryServiceFactory" 
+factory pid:</p>
+<div class="codehilite"><pre><span class="nd">@FactoryConfigurationAdapterService</span><span class="o">(</span><span class="n">factoryPid</span><span class="o">=</span><span class="s">&quot;DictionaryServiceFactory&quot;</span><span class="o">,</span> <span class="n">updated</span><span class="o">=</span><span class="s">&quot;updated&quot;</span><span class="o">)</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">DictionaryImpl</span> <span class="kd">implements</span> <span class="n">DictionaryService</span>
+<span class="o">{</span>
+    <span class="cm">/**</span>
+<span class="cm">      * The key of our config admin dictionary language.</span>
+<span class="cm">      */</span>
+    <span class="kd">final</span> <span class="kd">static</span> <span class="n">String</span> <span class="n">LANG</span> <span class="o">=</span> <span class="s">&quot;lang&quot;</span><span class="o">;</span>
+
+    <span class="cm">/**</span>
+<span class="cm">      * The key of our config admin dictionary values.</span>
+<span class="cm">      */</span>
+    <span class="kd">final</span> <span class="kd">static</span> <span class="n">String</span> <span class="n">WORDS</span> <span class="o">=</span> <span class="s">&quot;words&quot;</span><span class="o">;</span>
+
+    <span class="cm">/**</span>
+<span class="cm">      * We store all configured words in a thread-safe data structure, because ConfigAdmin</span>
+<span class="cm">      * may invoke our updated method at any time.</span>
+<span class="cm">      */</span>
+    <span class="kd">private</span> <span class="n">CopyOnWriteArrayList</span><span class="o">&lt;</span><span class="n">String</span><span class="o">&gt;</span> <span class="n">m_words</span> <span class="o">=</span> <span class="k">new</span> <span class="n">CopyOnWriteArrayList</span><span class="o">&lt;</span><span class="n">String</span><span class="o">&gt;();</span>
+
+    <span class="cm">/**</span>
+<span class="cm">      * Our Dictionary language.</span>
+<span class="cm">      */</span>
+    <span class="kd">private</span> <span class="n">String</span> <span class="n">m_lang</span><span class="o">;</span>
+
+    <span class="kd">protected</span> <span class="kt">void</span> <span class="nf">updated</span><span class="o">(</span><span class="n">Dictionary</span><span class="o">&lt;</span><span class="n">String</span><span class="o">,</span> <span class="o">?&gt;</span> <span class="n">config</span><span class="o">)</span> <span class="o">{</span>
+        <span class="n">m_lang</span> <span class="o">=</span> <span class="o">(</span><span class="n">String</span><span class="o">)</span> <span class="n">config</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="n">LANG</span><span class="o">);</span>
+        <span class="n">m_words</span><span class="o">.</span><span class="na">clear</span><span class="o">();</span>
+        <span class="n">String</span><span class="o">[]</span> <span class="n">words</span> <span class="o">=</span> <span class="o">(</span><span class="n">String</span><span class="o">[])</span> <span class="n">config</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="n">WORDS</span><span class="o">);</span>
+        <span class="k">for</span> <span class="o">(</span><span class="n">String</span> <span class="n">word</span> <span class="o">:</span> <span class="n">words</span><span class="o">)</span> <span class="o">{</span>
+            <span class="n">m_words</span><span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="n">word</span><span class="o">);</span>
+        <span class="o">}</span>
+     <span class="o">}</span>   
+         <span class="c1">// ...</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Here, this is the same example as above, but using meta types:</p>
+<div class="codehilite"><pre><span class="nd">@FactoryConfigurationAdapterService</span><span class="o">(</span>
+      <span class="n">factoryPid</span><span class="o">=</span><span class="s">&quot;DictionaryServiceFactory&quot;</span><span class="o">,</span> 
+      <span class="n">propagate</span><span class="o">=</span><span class="kc">true</span><span class="o">,</span> 
+      <span class="n">updated</span><span class="o">=</span><span class="s">&quot;updated&quot;</span><span class="o">,</span>
+      <span class="n">heading</span><span class="o">=</span><span class="s">&quot;Dictionary Services&quot;</span><span class="o">,</span>
+      <span class="n">description</span><span class="o">=</span><span class="s">&quot;Declare here some Dictionary instances, allowing to instantiates some DictionaryService services for a given dictionary language&quot;</span><span class="o">,</span>
+      <span class="n">metadata</span><span class="o">={</span>
+          <span class="nd">@PropertyMetaData</span><span class="o">(</span>
+                 <span class="n">heading</span><span class="o">=</span><span class="s">&quot;Dictionary Language&quot;</span><span class="o">,</span>
+                 <span class="n">description</span><span class="o">=</span><span class="s">&quot;Declare here the language supported by this dictionary. &quot;</span> <span class="o">+</span>
+                     <span class="s">&quot;This property will be propagated with the Dictionary Service properties.&quot;</span><span class="o">,</span>
+                 <span class="n">defaults</span><span class="o">={</span><span class="s">&quot;en&quot;</span><span class="o">},</span>
+                 <span class="n">id</span><span class="o">=</span><span class="n">DictionaryImpl</span><span class="o">.</span><span class="na">LANG</span><span class="o">,</span>
+                 <span class="n">cardinality</span><span class="o">=</span><span class="mi">0</span><span class="o">),</span>
+          <span class="nd">@PropertyMetaData</span><span class="o">(</span>
+                 <span class="n">heading</span><span class="o">=</span><span class="s">&quot;Dictionary words&quot;</span><span class="o">,</span>
+                 <span class="n">description</span><span class="o">=</span><span class="s">&quot;Declare here the list of words supported by this dictionary. This properties starts with a Dot and won&#39;t be propagated with Dictionary OSGi service properties.&quot;</span><span class="o">,</span>
+                 <span class="n">defaults</span><span class="o">={</span><span class="s">&quot;hello&quot;</span><span class="o">,</span> <span class="s">&quot;world&quot;</span><span class="o">},</span>
+                 <span class="n">id</span><span class="o">=</span><span class="n">DictionaryImpl</span><span class="o">.</span><span class="na">WORDS</span><span class="o">,</span>
+                 <span class="n">cardinality</span><span class="o">=</span><span class="n">Integer</span><span class="o">.</span><span class="na">MAX_VALUE</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">DictionaryImpl</span> <span class="kd">implements</span> <span class="n">DictionaryService</span>
+  <span class="o">{</span>
+     <span class="cm">/**</span>
+<span class="cm">       * The key of our config admin dictionary language.</span>
+<span class="cm">       */</span>
+     <span class="kd">final</span> <span class="kd">static</span> <span class="n">String</span> <span class="n">LANG</span> <span class="o">=</span> <span class="s">&quot;lang&quot;</span><span class="o">;</span>
+
+     <span class="cm">/**</span>
+<span class="cm">       * The key of our config admin dictionary values.</span>
+<span class="cm">       */</span>
+     <span class="kd">final</span> <span class="kd">static</span> <span class="n">String</span> <span class="n">WORDS</span> <span class="o">=</span> <span class="s">&quot;words&quot;</span><span class="o">;</span>
+
+     <span class="cm">/**</span>
+<span class="cm">       * We store all configured words in a thread-safe data structure, because ConfigAdmin</span>
+<span class="cm">       * may invoke our updated method at any time.</span>
+<span class="cm">       */</span>
+     <span class="kd">private</span> <span class="n">CopyOnWriteArrayList</span><span class="o">&lt;</span><span class="n">String</span><span class="o">&gt;</span> <span class="n">m_words</span> <span class="o">=</span> <span class="k">new</span> <span class="n">CopyOnWriteArrayList</span><span class="o">&lt;</span><span class="n">String</span><span class="o">&gt;();</span>
+
+     <span class="cm">/**</span>
+<span class="cm">       * Our Dictionary language.</span>
+<span class="cm">       */</span>
+     <span class="kd">private</span> <span class="n">String</span> <span class="n">m_lang</span><span class="o">;</span>
+
+     <span class="kd">protected</span> <span class="kt">void</span> <span class="nf">updated</span><span class="o">(</span><span class="n">Dictionary</span><span class="o">&lt;</span><span class="n">String</span><span class="o">,</span> <span class="o">?&gt;</span> <span class="n">config</span><span class="o">)</span> <span class="o">{</span>
+         <span class="n">m_lang</span> <span class="o">=</span> <span class="o">(</span><span class="n">String</span><span class="o">)</span> <span class="n">config</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="n">LANG</span><span class="o">);</span>
+         <span class="n">m_words</span><span class="o">.</span><span class="na">clear</span><span class="o">();</span>
+         <span class="n">String</span><span class="o">[]</span> <span class="n">words</span> <span class="o">=</span> <span class="o">(</span><span class="n">String</span><span class="o">[])</span> <span class="n">config</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="n">WORDS</span><span class="o">);</span>
+         <span class="k">for</span> <span class="o">(</span><span class="n">String</span> <span class="n">word</span> <span class="o">:</span> <span class="n">words</span><span class="o">)</span> <span class="o">{</span>
+             <span class="n">m_words</span><span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="n">word</span><span class="o">);</span>
+         <span class="o">}</span>
+     <span class="o">}</span>
+
+     <span class="c1">// ...</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
+      </div>
+      <div class="trademarkFooter"> 
+        Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project
+        logo are trademarks of The Apache Software Foundation. All other marks mentioned
+        may be trademarks or registered trademarks of their respective owners.
+      </div>
+    </div>
+  </body>
+</html>

Modified: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/component-resource-adapter.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/component-resource-adapter.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/component-resource-adapter.html Wed Mar  4 15:22:29 2015
@@ -68,9 +68,43 @@
       
       
       <h1></h1>
-      
+      <h4 id="resource-adapters">Resource Adapters</h4>
+<p>Resource adapters work just like adapters, but instead of working with services, they work with resources. Resources, represented as a URL, are an abstraction introduced to provide a generic way of dealing with "blobs" and can be resources inside a bundle, filesystem or some kind of data store.</p>
+<h2 id="resourceadapterservice">@ResourceAdapterService</h2>
+<p>Resource adapters are things that adapt a resource instead of a service, and 
+provide an adapter service on top of this resource. Resources are an 
+abstraction that is introduced by the dependency manager, represented as a URL. They can be implemented to serve resources embedded in bundles, somewhere on a file system or in an http content repository server, or database.</p>
+<p>The adapter will be applied to any resource that matches the specified filter 
+condition, which can match some part of the resource URL (with "path", 
+"protocol", "port", or "host" filters). For each matching resource an 
+adapter will be created based on the adapter implementation class. 
+The adapter will be registered with the specified interface and with any 
+extra service properties you supply here. Moreover, the following service 
+properties will be propagated from the resource URL:</p>
+<ul>
+<li><em>host</em>: this property exposes the host part of the resource URL</li>
+<li><em>path</em>: the resource URL path</li>
+<li><em>protocol</em>: the resource URL protocol</li>
+<li><em>port</em>: the resource URL port </li>
+</ul>
+<h3 id="annotation-attributes">Annotation attributes</h3>
+<p>TBD</p>
+<h3 id="usage-examples">Usage Examples:</h3>
+<p>Here, the "VideoPlayer" service provides a video service on top of any movie 
+resources, with service properties "host"/"port"/"protocol"/"path" extracted 
+from the resource URL:</p>
+<div class="codehilite"><pre><span class="nd">@ResourceAdapterService</span><span class="o">(</span><span class="n">filter</span> <span class="o">=</span> <span class="s">&quot;(&amp;(path=/videos/*.mkv)(host=localhost))&quot;</span><span class="o">,</span> <span class="n">propagate</span> <span class="o">=</span> <span class="kc">true</span><span class="o">)</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">VideoPlayerImpl</span> <span class="kd">implements</span> <span class="n">VideoPlayer</span> <span class="o">{</span>
+    <span class="c1">// Injected by reflection</span>
+    <span class="n">URL</span> <span class="n">resource</span><span class="o">;</span>
+
+    <span class="kt">void</span> <span class="nf">play</span><span class="o">()</span> <span class="o">{}</span> <span class="c1">// play video referenced by this.resource     </span>
+    <span class="kt">void</span> <span class="nf">stop</span><span class="o">()</span> <span class="o">{}</span> <span class="c1">// stop playing the video</span>
+    <span class="kt">void</span> <span class="nf">transcode</span><span class="o">()</span> <span class="o">{}</span> <span class="c1">// ...</span>
+<span class="o">}</span>
+</pre></div>
       <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
-        Rev. 1663924 by marrs on Wed, 4 Mar 2015 10:39:19 +0000
+        Rev. 1664040 by marrs on Wed, 4 Mar 2015 15:21:58 +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/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 15:22:29 2015
@@ -18,7 +18,7 @@
     limitations under the License.
 -->
   <head>
-    <title>Apache Felix - </title>
+    <title>Apache Felix - Apache Felix Dependency Manager - Components</title>
     <link rel="icon" href="/res/favicon.ico">
     <link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
     <link rel="stylesheet" href="/res/codehilite.css" type="text/css" media="all">
@@ -67,10 +67,197 @@
 
       
       
-      <h1></h1>
-      
+      <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>
+<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>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>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>
+<h2 id="composition">Composition</h2>
+<p>When implementing more complex components, you often find yourself using more than one instance. However, several of these instances might want to have dependencies injected. In such cases you need to tell the dependency manager which instances to consider. This has to be a fixed set of instances however.</p>
+<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>
+<p>This annotation annotates an implementation class that optionally publishes 
+an OSGi service, and optionally has some dependencies, with a managed 
+lifecycle. </p>
+<h3 id="annotation-attributes">Annotation attributes</h3>
+<hr />
+<p><strong><code>provides</code></strong>  <br />
+<em>Required</em>: No  <br />
+<em>Default</em>: all implemented interfaces, if any.   </p>
+<p>By default, the component is registered into the OSGi registry under all 
+directly implemented interfaces. If no interfaces are implemented, then the 
+component is not registered, but it still has a managed lifecycle, and may 
+have some dependencies. If you need to  explicitly define the list of 
+interfaces (or classes) under which the  component must be registered in the 
+OSGi registry, then use the <em>provides</em> attribute. You can also set this 
+property to an empty array of classes  if you don't want at all your component 
+to be exposed in the OSGi  registry (even if it implements some interfaces).</p>
+<hr />
+<p><strong><code>properties</code></strong>  <br />
+<em>Required</em>: No  <br />
+<em>Default</em>: --  </p>
+<p>the <em>properties" attribute enumerates the list of properties that are part of 
+the Service exposed by the component in the OSGi Registry. 
+Each property is defined using the @Property annotation, which represents a<br />
+key/value pair. When a value is actually an array of strings, 
+then the </em>values* attribute of the @Property annotation can be used. 
+This attribute  is not the only way to specify OSGi Service properties 
+(see Setting Service properties in the lifecycle section).</p>
+<hr />
+<p><strong><code>factoryMethod</code></strong>  <br />
+<em>Required</em>: No  <br />
+<em>Default</em>: --  </p>
+<p>This attribute refers to a static method name from the annotated class which 
+can be used to instantiate the component instance. Normally, DependencyManager 
+instantiates the component using its class name, and with the default 
+constructor of the class, but there are some cases where it is required to 
+take control of  how the component is created. For instance, this method may 
+be used to create the component as a dynamic proxy ...</p>
+<hr />
+<p><strong><code>factorySet</code></strong>  <br />
+<em>Required</em>: No  <br />
+<em>Default</em>: --  </p>
+<p>This attribute is the identifier for a component factory. By default, a 
+component is automatically instantiated as a singleton when the bundle is 
+started, and when all required dependencies are satisfied. But when a 
+component must be created, configured, or disposed dynamically, and when 
+multiple instances of the same component are needed, a factorySet should  be 
+used. When you use this attribute, a java.util.Set<Dictionary>  object is 
+registered into the OSGi regitry, with a specific <em>dm.factory.name</em> service 
+property matching the ID you specify in the attribute. </p>
+<p>This Set<Dictionary> will act as a Factory API, and another component may 
+define a dependency on this Set and add some configuration dictionaries in it, 
+in order to fire some component instantiation/activation. There is one 
+component instantiated per added dictionary, which is passed to component 
+instances via a configurable callback method (using the <em>factoryConfigure</em> 
+attribute). All public properties will be propagated  along with eventual 
+published service. A public property is a property  which does not start with 
+a dot ("."). Properties starting with a dot are considered private to the 
+component, and won't be propagated to published service. This model is 
+actually similar to the Declarative Service "Component Factories" concept, 
+except that you don't have a dependency on a specific API, but rather on a 
+basic jdk class  (java.util.Set<Dictionary>). </p>
+<p>Notice that, unlike in Declarative Service, the component factory is provided once the component 
+bundle is started, even if required dependencies are not satisfied. This is 
+useful when the component want  to dynamically configure its dependency 
+filters. So, to summarize:</p>
+<ul>
+<li>Each time a new Dictionary is added into the Set, then a new instance of the annotated component will be instantiated, and this dictionary is passed to the component callback specified with the factoryConfigure attribute.</li>
+<li>Each time an existing Dictionary is re-added into the Set, then the corresponding component instance is updated, and the updated dictionary is also passed to the callback specified in the factoryConfigure attribute.</li>
+<li>Each time an existing Dictionary is removed from the Set, then the  corresponding component instance will be stopped and destroyed.</li>
+</ul>
+<hr />
+<p><strong><code>factoryConfigure</code></strong>  <br />
+<em>Required</em>: No  <br />
+<em>Default</em>: --  </p>
+<p>This attributes sets the <em>configure</em> method name to be called with the factory 
+configuration. This attribute only makes sense if the factorySet() attribute 
+is used. If specified, then this attribute references a component callback 
+method, which is called for providing the configuration supplied by the 
+factory that instantiated this component. The current Service properties will 
+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="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">&quot;MyPid&quot;</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 service.</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>
+        <span class="c1">// Our component is starting and is about to be registered 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>
+        <span class="c1">// ...</span>
+    <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Example using a factorySet, where the X component is instantiated/updated/disposed by another Y component:</p>
+<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">&quot;MyComponentFactory&quot;</span><span class="o">,</span> <span class="n">factoryConfigure</span><span class="o">=</span><span class="s">&quot;configure&quot;</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&#39;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="o">}</span>
+
+     <span class="nd">@ServiceDependency</span>
+     <span class="kt">void</span> <span class="nf">bindOtherService</span><span class="o">(</span><span class="n">OtherService</span> <span class="n">other</span><span class="o">)</span> <span class="o">{</span>
+         <span class="c1">// store this require dependency</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>
+         <span class="c1">// Our component is starting and is about to be registered 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>
+         <span class="c1">// ... part of Z interface</span>
+     <span class="o">}</span>
+ <span class="o">}</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">@ServiceDependency</span><span class="o">(</span><span class="n">filter</span><span class="o">=</span><span class="s">&quot;(dm.factory.name=MyComponentFactory)&quot;</span><span class="o">)</span>
+     <span class="n">Set</span><span class="o">&lt;</span><span class="n">Dictionary</span><span class="o">&gt;</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="nd">@Start</span>
+     <span class="kt">void</span> <span class="nf">start</span><span class="o">()</span> <span class="o">{</span>
+         <span class="c1">// Instantiate a X component instance</span>
+         <span class="n">Dictionary</span> <span class="n">x1</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Hashtable</span><span class="o">()</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">// Instantiate another X component instance</span>
+         <span class="n">Dictionary</span> <span class="n">x2</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Hashtable</span><span class="o">()</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">x2</span><span class="o">);</span>
+
+         <span class="c1">// Update the first X component instance</span>
+         <span class="n">x1</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">&quot;foo&quot;</span><span class="o">,</span> <span class="s">&quot;bar1_modified&quot;</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="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. 1663924 by marrs on Wed, 4 Mar 2015 10:39:19 +0000
+        Rev. 1664040 by marrs on Wed, 4 Mar 2015 15:21:58 +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 15:22:29 2015
@@ -68,9 +68,20 @@
       
       
       <h1></h1>
-      
+      <h3 id="dependencies">Dependencies</h3>
+<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>
+<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>
+<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>
+<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. 1663924 by marrs on Wed, 4 Mar 2015 10:39:19 +0000
+        Rev. 1664040 by marrs on Wed, 4 Mar 2015 15:21:58 +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/dependency-bundle.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/dependency-bundle.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/dependency-bundle.html Wed Mar  4 15:22:29 2015
@@ -68,9 +68,41 @@
       
       
       <h1></h1>
-      
+      <h5 id="bundle">Bundle</h5>
+<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</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="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-lifecycle.html">Here</a>.</li>
+</ul>
+<p>Usage Examples</p>
+<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">&quot;unloadServiceComponents&quot;</span><span class="o">,</span>
+                      <span class="n">filter</span> <span class="o">=</span> <span class="s">&quot;(Service-Component=*)&quot;</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">&quot;Service-Component&quot;</span><span class="o">);</span>
+        <span class="c1">// load all service component specified in the XML descriptorPaths files ...</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 &quot;loadServiceComponents&quot; method.</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. 1663924 by marrs on Wed, 4 Mar 2015 10:39:19 +0000
+        Rev. 1664040 by marrs on Wed, 4 Mar 2015 15:21:58 +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/dependency-configuration.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/dependency-configuration.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/dependency-configuration.html Wed Mar  4 15:22:29 2015
@@ -68,9 +68,62 @@
       
       
       <h1></h1>
-      
+      <h5 id="configuration">Configuration</h5>
+<p>A configuration dependency is always required, and allows you to depend on the availability of a valid configuration for your component. Optional configuration dependencies are not supported because in that case you can just as well register as a <code>ManagedService</code> yourself.</p>
+<h2 id="configurationdependency">@ConfigurationDependency</h2>
+<p>A configuration dependency is always required, and allows you to depend on the availability of a valid configuration for your component. This dependency requires the OSGi Configuration Admin Service.</p>
+<p>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>
+<li><em>heading</em>: The label used to display the tab name (or section) where the properties are displayed. Example: "Printer Service".</li>
+<li><em>description</em>: A human readable description of the PID this annotation is associated with. Example: "Configuration for the PrinterService bundle".</li>
+<li><em>metadata</em>: an array of PropertyMetadaData[]() annotation describing property types (see the FactoryConfigurationAdapterService section in the "Writing Components" section.</li>
+</ul>
+<p>Usage Examples</p>
+<p>In the following example, the "Printer" component depends on a configuration whose PID name is "org.apache.felix.sample.Printer". This service will initialize its ip/port number from the provided configuration:</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 ...</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="o">(</span>
+        <span class="n">heading</span> <span class="o">=</span> <span class="s">&quot;Printer Service&quot;</span><span class="o">,</span>
+        <span class="n">description</span> <span class="o">=</span> <span class="s">&quot;Declare here parameters used to configure the Printer service&quot;</span><span class="o">,</span>
+        <span class="n">metadata</span> <span class="o">=</span> <span class="o">{</span>
+            <span class="nd">@PropertyMetaData</span><span class="o">(</span><span class="n">heading</span> <span class="o">=</span> <span class="s">&quot;Ip Address&quot;</span><span class="o">,</span>
+                              <span class="n">description</span> <span class="o">=</span> <span class="s">&quot;Enter the ip address for the Printer service&quot;</span><span class="o">,</span>
+                              <span class="n">defaults</span> <span class="o">=</span> <span class="o">{</span> <span class="s">&quot;127.0.0.1&quot;</span> <span class="o">},</span>
+                              <span class="n">type</span> <span class="o">=</span> <span class="n">String</span><span class="o">.</span><span class="na">class</span><span class="o">,</span>
+                              <span class="n">id</span> <span class="o">=</span> <span class="s">&quot;IPADDR&quot;</span><span class="o">,</span>
+                              <span class="n">cardinality</span> <span class="o">=</span> <span class="mi">0</span><span class="o">),</span>
+            <span class="nd">@PropertyMetaData</span><span class="o">(</span><span class="n">heading</span> <span class="o">=</span> <span class="s">&quot;Port Number&quot;</span><span class="o">,</span>
+                              <span class="n">description</span> <span class="o">=</span> <span class="s">&quot;Enter the port number for the Printer service&quot;</span><span class="o">,</span>
+                              <span class="n">defaults</span> <span class="o">=</span> <span class="o">{</span> <span class="s">&quot;4444&quot;</span> <span class="o">},</span>
+                              <span class="n">type</span> <span class="o">=</span> <span class="n">Integer</span><span class="o">.</span><span class="na">class</span><span class="o">,</span>
+                              <span class="n">id</span> <span class="o">=</span> <span class="s">&quot;PORTNUM&quot;</span><span class="o">,</span>
+                              <span class="n">cardinality</span> <span class="o">=</span> <span class="mi">0</span><span class="o">)</span>
+             <span class="o">}</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="n">config</span><span class="o">)</span> <span class="o">{</span>
+        <span class="c1">// load configuration from the provided dictionary.</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. 1663924 by marrs on Wed, 4 Mar 2015 10:39:19 +0000
+        Rev. 1664040 by marrs on Wed, 4 Mar 2015 15:21:58 +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/dependency-resource.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/dependency-resource.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/dependency-resource.html Wed Mar  4 15:22:29 2015
@@ -68,9 +68,88 @@
       
       
       <h1></h1>
-      
+      <h5 id="resource">Resource</h5>
+<p>A resource dependency allows you to depend on a resource. A resource is a URL and you can use a filter condition based on protocol, host, port, path and URL.</p>
+<h2 id="resourcedependency">@ResourceDependency</h2>
+<p>Annotates a method of field as a Resource Dependency. A resource dependency allows you to depend on a resource. Resources are an abstraction that is introduced by the dependency manager, represented as a URL. They can be implemented to serve resources embedded in bundles, somewhere on a file system or in an http content repository server, or database.
+A resource is a URL and you can use a filter condition based on protocol, host, port, and path.</p>
+<p>Attributes:</p>
+<ul>
+<li><em>added</em>: Returns the callback method to be invoked when the service is available. This attribute is only meaningful when the annotation is applied on a class field.</li>
+<li><em>changed</em>: Returns the callback method to be invoked when the service properties 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 Service dependency is required or not.</li>
+<li><em>filter</em>: Returns the Service dependency OSGi filter.</li>
+<li><em>propagate</em>: Specifies if the resource URL properties must be propagated. If set to true, then the URL properties ("protocol"/"host"/"port"/"path") will be propagated to the service properties of the component which is using this dependency.</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="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-lifecycle.html">Here</a>.</li>
+</ul>
+<p>Usage Examples
+Here, the "VideoPlayer" component plays any provided MKV video resources</p>
+<div class="codehilite"><pre><span class="nd">@Component</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">VideoPlayer</span> <span class="o">{</span>
+    <span class="nd">@ResourceDependency</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">filter</span><span class="o">=</span><span class="s">&quot;(path=/videos/*.mkv)&quot;</span><span class="o">)</span>
+    <span class="kt">void</span> <span class="nf">playResource</span><span class="o">(</span><span class="n">URL</span> <span class="n">video</span><span class="o">)</span> <span class="o">{</span> <span class="o">...</span> <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>And here is an example of a VideoProvider, which provides some videos using a web URL. Notice that Resource providers need to depend on the DependencyManager API:</p>
+<div class="codehilite"><pre><span class="kn">import</span> <span class="nn">java.net.MalformedURLException</span><span class="o">;</span>
+<span class="kn">import</span> <span class="nn">java.net.URL</span><span class="o">;</span>
+<span class="kn">import</span> <span class="nn">java.util.HashMap</span><span class="o">;</span>
+<span class="kn">import</span> <span class="nn">java.util.Map</span><span class="o">;</span>
+
+<span class="kn">import</span> <span class="nn">org.apache.felix.dm.ResourceHandler</span><span class="o">;</span>
+<span class="kn">import</span> <span class="nn">org.apache.felix.dm.ResourceUtil</span><span class="o">;</span>
+<span class="kn">import</span> <span class="nn">org.apache.felix.dm.annotation.api.Component</span><span class="o">;</span>
+<span class="kn">import</span> <span class="nn">org.apache.felix.dm.annotation.api.Init</span><span class="o">;</span>
+<span class="kn">import</span> <span class="nn">org.apache.felix.dm.annotation.api.ServiceDependency</span><span class="o">;</span>
+<span class="kn">import</span> <span class="nn">org.osgi.framework.BundleContext</span><span class="o">;</span>
+<span class="kn">import</span> <span class="nn">org.osgi.framework.Filter</span><span class="o">;</span>
+<span class="kn">import</span> <span class="nn">org.osgi.framework.InvalidSyntaxException</span><span class="o">;</span>
+
+<span class="nd">@Component</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">VideoProvider</span>
+<span class="o">{</span>
+    <span class="c1">// Injected by reflection</span>
+    <span class="kd">private</span> <span class="kd">volatile</span> <span class="n">BundleContext</span> <span class="n">context</span><span class="o">;</span>
+    <span class="c1">// List of known resource handlers</span>
+    <span class="kd">private</span> <span class="n">Map</span><span class="o">&lt;</span><span class="n">ResourceHandler</span><span class="o">,</span> <span class="n">Filter</span><span class="o">&gt;</span> <span class="n">m_handlers</span> <span class="o">=</span> <span class="k">new</span> <span class="n">HashMap</span><span class="o">&lt;</span><span class="n">ResourceHandler</span><span class="o">,</span> <span class="n">Filter</span><span class="o">&gt;();</span>
+    <span class="c1">// List of known video resources</span>
+    <span class="kd">private</span> <span class="n">URL</span><span class="o">[]</span> <span class="n">m_videos</span><span class="o">;</span>
+
+    <span class="nd">@Init</span>
+    <span class="kt">void</span> <span class="nf">init</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">MalformedURLException</span>
+    <span class="o">{</span>
+       <span class="n">m_videos</span> <span class="o">=</span> <span class="k">new</span> <span class="n">URL</span><span class="o">[]</span> <span class="o">{</span>
+               <span class="k">new</span> <span class="nf">URL</span><span class="o">(</span><span class="s">&quot;http://localhost:8080/videos/video1.mkv&quot;</span><span class="o">),</span>
+               <span class="k">new</span> <span class="nf">URL</span><span class="o">(</span><span class="s">&quot;http://localhost:8080/videos/video2.mkv&quot;</span><span class="o">),</span>
+        <span class="o">};</span>
+    <span class="o">}</span>
+
+    <span class="c1">// Track resource handlers</span>
+    <span class="nd">@ServiceDependency</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="kd">public</span> <span class="kt">void</span> <span class="nf">add</span><span class="o">(</span><span class="n">Map</span><span class="o">&lt;</span><span class="n">String</span><span class="o">,</span> <span class="n">String</span><span class="o">&gt;</span> <span class="n">serviceProperties</span><span class="o">,</span> <span class="n">ResourceHandler</span> <span class="n">handler</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">InvalidSyntaxException</span>
+    <span class="o">{</span>
+        <span class="n">String</span> <span class="n">filterString</span> <span class="o">=</span> <span class="n">serviceProperties</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">&quot;filter&quot;</span><span class="o">);</span>
+        <span class="n">filterString</span> <span class="o">=</span> <span class="o">(</span><span class="n">filterString</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">)</span> <span class="o">?</span> <span class="n">filterString</span> <span class="o">:</span> <span class="s">&quot;(path=*)&quot;</span><span class="o">;</span>
+        <span class="n">Filter</span> <span class="n">filter</span> <span class="o">=</span> <span class="n">context</span><span class="o">.</span><span class="na">createFilter</span><span class="o">(</span><span class="n">filterString</span><span class="o">);</span>
+        <span class="kd">synchronized</span> <span class="o">(</span><span class="k">this</span><span class="o">)</span>
+        <span class="o">{</span>
+            <span class="n">m_handlers</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="n">handler</span><span class="o">,</span> <span class="n">filter</span><span class="o">);</span>
+        <span class="o">}</span>
+        <span class="k">for</span> <span class="o">(</span><span class="n">URL</span> <span class="n">video</span> <span class="o">:</span> <span class="n">m_videos</span><span class="o">)</span>
+        <span class="o">{</span>
+            <span class="k">if</span> <span class="o">(</span><span class="n">filter</span><span class="o">.</span><span class="na">match</span><span class="o">(</span><span class="n">ResourceUtil</span><span class="o">.</span><span class="na">createProperties</span><span class="o">(</span><span class="n">video</span><span class="o">)))</span>
+            <span class="o">{</span>
+                <span class="n">handler</span><span class="o">.</span><span class="na">added</span><span class="o">(</span><span class="n">video</span><span class="o">);</span>
+            <span class="o">}</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. 1663924 by marrs on Wed, 4 Mar 2015 10:39:19 +0000
+        Rev. 1664040 by marrs on Wed, 4 Mar 2015 15:21:58 +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/dependency-service.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/dependency-service.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/dependency-service.html Wed Mar  4 15:22:29 2015
@@ -68,9 +68,77 @@
       
       
       <h1></h1>
-      
+      <h5 id="service">Service</h5>
+<p>A service dependency allows you to depend on a service, either by type or by using an additional filter condition. You can even depend on an existing service directly by providing a reference to it.</p>
+<h2 id="servicedependency">@ServiceDependency</h2>
+<p>Annotates a method or a field for injecting a Service Dependency on it. When applied on a class field, optional unavailable dependencies are injected with a NullObject.</p>
+<p>Annotation attributes:</p>
+<ul>
+<li><em>added</em>: The callback method to be invoked when the service is available. This attribute is only meaningful when the annotation is applied on a class field.</li>
+<li><em>changed</em>: The callback method to be invoked when the service properties have changed.</li>
+<li><em>removed</em>: The callback method to invoke when the service is lost.</li>
+<li><em>timeout</em>: The max time in millis to wait for when the dependency is temporarily unavailable. Specifying a positive number allow to block the caller thread between service updates. Only useful for required stateless dependencies that can be replaced transparently. A Dynamic Proxy is used to wrap the actual service dependency (which must be an interface). When the dependency goes away, an attempt is made to replace it with another one which satisfies the service dependency criteria. If no service replacement is available, then any method invocation (through the dynamic proxy) will block during a configurable timeout. On timeout, an unchecked IllegalStateException exception is raised (but the service is not deactivated).
+Notice that the changed/removed callbacks are not used when the timeout parameter is &gt; -1.
+-1 means no timeout at all (default). 0 means that invocation on a missing service will fail immediately. A positive number represents the max timeout in millis to wait for the service availability.</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="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-lifecycle.html">Here</a> for more informations about named dependencies.</li>
+<li><em>propagate</em>: Returns true if the dependency service properties must be published along with the service. Any additional service properties specified directly are merged with these.</li>
+</ul>
+<p>Usage Example: Here, the MyComponent component is injected with a dependency over a "MyDependency" service.</p>
+<div class="codehilite"><pre><span class="nd">@Component</span>
+<span class="kd">class</span> <span class="nc">MyComponent</span> <span class="o">{</span>
+     <span class="nd">@ServiceDependency</span><span class="o">(</span><span class="n">timeout</span><span class="o">=</span><span class="mi">15000</span><span class="o">)</span>
+     <span class="n">MyDependency</span> <span class="n">dependency</span><span class="o">;</span>
+     <span class="c1">// ...</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Usage example of a Service whose dependency filter is configured from ConfigAdmin, using a "named" dependency
+(please check <a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-lifecycle.html">Here</a> for more informations about "named" dependencies):</p>
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm">  * A Service whose service dependency &quot;otherService&quot; filter is configured from ConfigAdmin</span>
+<span class="cm">  */</span>
+<span class="nd">@Service</span>
+<span class="kd">class</span> <span class="nc">X</span> <span class="o">{</span>
+    <span class="kd">private</span> <span class="n">Dictionary</span> <span class="n">m_config</span><span class="o">;</span>
+
+     <span class="cm">/**</span>
+<span class="cm">       * Initialize our service from config ... and store the config for later usage (from our init method)</span>
+<span class="cm">       */</span>
+     <span class="nd">@ConfigurationDependency</span><span class="o">(</span><span class="n">pid</span><span class="o">=</span><span class="s">&quot;MyPid&quot;</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="n">m_config</span> <span class="o">=</span> <span class="n">config</span><span class="o">;</span>
+     <span class="o">}</span>
+
+     <span class="cm">/**</span>
+<span class="cm">      * All unnamed dependencies are injected: we can now configure other named</span>
+<span class="cm">      * dependencies, using the already injected configuration.</span>
+<span class="cm">      * The returned Map will be used to configure our &quot;otherService&quot; Dependency.</span>
+<span class="cm">      */</span>
+     <span class="nd">@Init</span>
+     <span class="n">Map</span> <span class="nf">init</span><span class="o">()</span> <span class="o">{</span>
+         <span class="k">return</span> <span class="k">new</span> <span class="nf">HashMap</span><span class="o">()</span> <span class="o">;</span>
+     <span class="o">}</span>
+
+     <span class="cm">/**</span>
+<span class="cm">      * This named dependency filter/required flag will be configured by our init method (see above).</span>
+<span class="cm">      */</span>
+     <span class="nd">@ServiceDependency</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="s">&quot;otherService&quot;</span><span class="o">)</span>
+         <span class="kt">void</span> <span class="nf">bindOtherService</span><span class="o">(</span><span class="n">OtherService</span> <span class="n">other</span><span class="o">)</span> <span class="o">{</span>
+     <span class="o">}</span>
+
+     <span class="cm">/**</span>
+<span class="cm">      * All dependencies are injected and our service is now ready to be published.</span>
+<span class="cm">      * Notice that you can also use the publisher service attribute if you need</span>
+<span class="cm">      * to take control on service exposition.</span>
+<span class="cm">      */</span>
+     <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="o">}</span>
+ <span class="o">}</span>
+</pre></div>
       <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
-        Rev. 1663924 by marrs on Wed, 4 Mar 2015 10:39:19 +0000
+        Rev. 1664040 by marrs on Wed, 4 Mar 2015 15:21:58 +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/external-links.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/external-links.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/external-links.html Wed Mar  4 15:22:29 2015
@@ -68,9 +68,16 @@
       
       
       <h1></h1>
-      
+      <p>Title: Dependency Manager Resources
+Excerpt: Dependency Manager articles and resources</p>
+<p>This page regroups Dependency Manager external articles and related links.</p>
+<ul>
+<li><a href="https://bitbucket.org/marrs/bndtools-dmdemo">BndTools based demo of Dependency Manager annotations</a></li>
+<li><a href="http://arnhem.luminis.eu/introduction-apache-felix-dependency-manager">Introduction to Dependency Manager</a></li>
+<li><a href="http://arnhem.luminis.eu/introduction-apache-felix-dependencymanager-part-2">Introduction to Dependency Manager, part II</a></li>
+</ul>
       <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
-        Rev. 1663924 by marrs on Wed, 4 Mar 2015 10:39:19 +0000
+        Rev. 1664040 by marrs on Wed, 4 Mar 2015 15:21:58 +0000
       </div>
       <div class="trademarkFooter"> 
         Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project



Mime
View raw message