felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r879262 - in /websites/staging/felix/trunk/content: ./ documentation/subprojects/apache-felix-dependency-manager/ documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/
Date Fri, 20 Sep 2013 22:55:07 GMT
Author: buildbot
Date: Fri Sep 20 22:55:06 2013
New Revision: 879262

Log:
Staging update by buildbot for felix

Added:
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-dependencies.html
Removed:
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/apache-felix-dependency-manager-using-annotations-dependencies.html
Modified:
    websites/staging/felix/trunk/content/   (props changed)
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations.html
    websites/staging/felix/trunk/content/sitemap.html

Propchange: websites/staging/felix/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Fri Sep 20 22:55:06 2013
@@ -1 +1 @@
-1525164
+1525166

Modified: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations.html
(original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations.html
Fri Sep 20 22:55:06 2013
@@ -84,14 +84,14 @@ components can interact with the dynamic
 <ul>
 <li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-quickstart.html">Provides
an &quot;Hello World&quot; example, and shows how to compile it.</a></li>
 <li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-spellchecker.html">Helps
you with the basic concepts using a full SpellChecker sample code.</a></li>
-<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-component.html">Explains
how to write Dependency Manager service components using annotations</a></li>
-<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/apache-felix-dependency-manager-using-annotations-dependencies.html">Using
Dependencies</a> Explains how to annotate dependencies for a given component.</li>
+<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-component.html">Explains
how to write Dependency Manager service components using annotations.</a></li>
+<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-dependencies.html">Explains
how to annotate component dependencies.</a></li>
 <li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/apache-felix-dependency-manager-using-annotations-lifecycle.html">Lifecycle</a>
Explains the DM component lifecycle and how components interact with the dynamic OSGI service
model.</li>
 <li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/apache-felix-dependency-manager-using-annotations-composition.html">Composition</a>
Explains how a component may be implemented using multiple object instances.</li>
 <li><a href="https://bitbucket.org/marrs/bndtools-dmdemo">BndTools Tutorial</a>
A BndTools based demo of DependencyManager annotations.</li>
 </ul>
       <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
-        Rev. 1525160 by pderop on Fri, 20 Sep 2013 22:31:51 +0000
+        Rev. 1525166 by pderop on Fri, 20 Sep 2013 22:51:11 +0000
       </div>
       <div class="trademarkFooter"> 
         Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project

Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-dependencies.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-dependencies.html
(added)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-dependencies.html
Fri Sep 20 22:55:06 2013
@@ -0,0 +1,321 @@
+<!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 - Dependency Manager Dependencies Annotations</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.html">Apache Felix Dependency
Manager</a>&nbsp;&raquo&nbsp;<a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations.html">Dependency
Manager Annotations</a>
+      </div>
+
+      
+      <div class="tip">
+           This page is a translated version of <a href="/site/dependencymanager-annotations-dependencies.html"
target="felix_cwiki">/site/dependencymanager-annotations-dependencies.html</a>. In
case of
+           doubt you might want to refer to the old page.
+      </div>
+      
+      
+      <h1>Dependency Manager Dependencies Annotations</h1>
+      <p>This section describes the various dependencies supported with annotations.</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="">Apache Felix Dependency Manager - Using Annotations - Lifecycle#Dynamic
Dependency Configuration</a>.</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="">Apache Felix Dependency Manager - Using Annotations - Lifecycle#Dynamic
Dependency Configuration</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>
+
+
+<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>
+
+
+<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="">Apache Felix Dependency Manager - Using Annotations - Lifecycle#Dynamic
Dependency Configuration</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>
+
+
+<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="">Apache Felix Dependency Manager - Using Annotations - Lifecycle#Dynamic
Dependency Configuration</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. 1525166 by pderop on Fri, 20 Sep 2013 22:51:11 +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/sitemap.html
==============================================================================
--- websites/staging/felix/trunk/content/sitemap.html (original)
+++ websites/staging/felix/trunk/content/sitemap.html Fri Sep 20 22:55:06 2013
@@ -121,9 +121,9 @@
 <li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations.html">Dependency
Manager Annotations</a><ul>
 <li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/apache-felix-dependency-manager-how-to-build.html">Apache
Felix Dependency Manager - How To Build</a></li>
 <li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/apache-felix-dependency-manager-using-annotations-composition.html">Apache
Felix Dependency Manager - Using Annotations - Composition</a></li>
-<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/apache-felix-dependency-manager-using-annotations-dependencies.html">Apache
Felix Dependency Manager - Using Annotations - Dependencies</a></li>
 <li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/apache-felix-dependency-manager-using-annotations-lifecycle.html">Apache
Felix Dependency Manager - Using Annotations - Lifecycle</a></li>
-<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-component.html">Apache
Felix Dependency Manager - Using Annotations - Components</a></li>
+<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-component.html">Dependency
Manager Components Annotations</a></li>
+<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-dependencies.html">Dependency
Manager Dependencies Annotations</a></li>
 <li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-quickstart.html">Dependency
Manager Annotations Quick Start</a></li>
 <li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-spellchecker.html">Dependency
Manager SpellChecker Sample</a></li>
 </ul>



Mime
View raw message