Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/whatsnew.html ============================================================================== --- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/whatsnew.html (added) +++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/whatsnew.html Tue Mar 10 21:03:25 2015 @@ -0,0 +1,143 @@ +<!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 - Apache Felix Dependency Manager - What's new in version 4?</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> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/subprojects.html">Apache Felix Subproject Documentation</a> » <a href="/documentation/subprojects/apache-felix-dependency-manager.html">Apache Felix Dependency Manager 4</a> + </div> + + + + <h1>Apache Felix Dependency Manager - What's new in version 4?</h1> + <h2 id="new-thread-model">New thread model</h2> +<p>DependencyManager 4.0 has been significantly reworked to improve support for concurrency. The following principles form the basis of the new concurrency model in DM4.</p> +<ul> +<li>All external events that influence the state of dependencies are recorded and given to the serial executor of the component. We record whatever data comes in, so when the actual job is run by the serial executor, we still have access to the original data without having to access other sources whose state might have changed since.</li> +<li>The serial executor of a component will execute a job immediately if it is being called by the thread that is already executing jobs.</li> +<li>If the serial executor of a component had not yet started a job, it will queue and start it on the current thread.</li> +<li>If the serial executor gets invoked from a different thread than the one currently executing jobs, the job will be put at the end of the queue. As mentioned before, any data associated with the event will also be recorded so it is available when the job executes.</li> +<li>State in the component and dependency can only be modified via the serial executor thread. This means we don't need explicit synchronization anywhere.</li> +</ul> +<p>DependencyManager 4 now also supports parallel execution of component wiring.</p> +<p>Added support for parallelism: To allow components to be started and handled in parallel, you can now register in the OSGi service registry a ComponentExecutorFactory service that is used to get an Executor for the management of all components dependencies/lifecycle callbacks. See javadoc from the org.apache.felix.dm.ComponentExecutorFactory interface for more information.</p> +<p>You can also take a look at the the org.apache.felix.dependencymanager.samples project, which is registering a ComponentExecutorFactory from org.apache.felix.dependencymanager.samples.tpool bundle.</p> +<p>See also the following property in the org.apache.felix.dependencymanager.samples/bnd.bnd </p> +<div class="codehilite"><pre><span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">felix</span><span class="p">.</span><span class="n">dependencymanager</span><span class="p">.</span><span class="n">parallel</span><span class="p">=</span><span class="o">\</span> + <span class="s">'!org.apache.felix.dependencymanager.samples.tpool, *'</span><span class="p">,</span><span class="o">\</span> +</pre></div> + + +<p>Here, all components will be handled by Executors provided by the ComponentExecutorFactory, except those having a package starting with "org.apache.felix.dependencymanager.samples.tpool" (because the threadpool is itself defined using the Dependency Manager API).</p> +<p>You will find a full description of the new thread model in the <a href="../reference/thread-model.html">Reference</a> section.</p> +<h2 id="new-features">New features</h2> +<p>In addition, some new features have been implemented in dependency manager:</p> +<ul> +<li> +<p>Auto Config Iterable fields: AutoConfig dependencies can be applied on Iterable<Service> fields in order to be able to traverse currently injected services safely. The Iterable must be parameterized with the Service type. +<a href="https://svn.apache.org/repos/asf/felix/trunk/dependencymanager/org.apache.felix.dependencymanager.samples/src/org/apache/felix/dependencymanager/samples/dictionary/api/SpellChecker.java";>see this sample code</a> from the source distribution samples.</p> +</li> +<li> +<p>AutoConfig Map field: AutoConfig dependencies can be applied on a field with a Map<Service, Dictionary> type, allowing to traverse currently injected services safely, including service properties. The Map must be traversed using the Map.Entry iterator. +See the <em>ServiceDependency.setAutConfig(boolean autoConfig)</em> <a href="http://felix.apache.org/apidocs/dependencymanager/4.0.0/org/apache/felix/dm/ServiceDependency.html";>javadoc</a> for more more informations.</p> +</li> +<li> +<p>Inject Configuration on separate callback instance (FELIX-2707): Configuration can be injected on a separate callback instance, like a CompositionManager for example. +See the <a href="https://svn.apache.org/repos/asf/felix/trunk/dependencymanager/org.apache.felix.dependencymanager.samples/src/org/apache/felix/dependencymanager/samples/compositefactory/";>composite factory example</a> example available from the source distribution.</p> +</li> +<li> +<p>Added <em>propagate</em> flag in service Adapters (FELIX-4600): you can now choose to propagate or not adaptee service properties.</p> +</li> +<li> +<p>"Top" command in the shell: a "top" command is now available from the shell and can be used to display all top components sorted by their init/start elapsed time.</p> +</li> +<li> +<p>The Annotations plugin can now automatically generate a Require-Capability header on the Dependency Manager Runtime bundle. +Use "add-require-capability=true" option in the plugin declaration property to enable this new feature (see FELIX-4676):</p> +<p>-plugin: org.apache.felix.dm.annotation.plugin.bnd.AnnotationPlugin; add-require-capability=true</p> +</li> +<li> +<p>The Configuration Dependency annotation now supports a "name" attribute (FELIX-4777): allow to dynamically configure configuration pids from the @Init method.</p> +</li> +<li> +<p>Added a benchmark tool for dependency manager (not released, only available from the <a href="https://svn.apache.org/repos/asf/felix/trunk/dependencymanager/org.apache.felix.dependencymanager.benchmark/";>trunk</a>.</p> +</li> +<li> +<p>The Annotations "Factory Sets" are deprecated (FELIX-4684): You can now use a DS-like ComponentFactory API by a nice api which is exported by the runtime bundle. +See this <a href="https://svn.apache.org/repos/asf/felix/trunk/dependencymanager/org.apache.felix.dependencymanager.samples/src/org/apache/felix/dependencymanager/samples/device/annot/DeviceAndParameterFactory.java";>example</a> from the samples in the source distribution.</p> +</li> +</ul> +<h2 id="sample-codes">Sample codes</h2> +<p>The source distribution includes many sample codes which can be run directly under Eclipse and BndTools. The samples are available in the +org.apache.felix.dependencymanager.samples/ module. +Some of the samples require that you configure some pids or factory pids from Web Console, which can be accessed using <em>http://localhost:8080/system/console/configMgr</em> URL. +Please consult org.apache.felix.dependencymanager.samples/README.samples for up to date instructions on how to execute the various examples.</p> + <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;"> + Rev. 1665491 by pderop on Tue, 10 Mar 2015 12:05:33 +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>
Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-adapter.html ============================================================================== --- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-adapter.html (added) +++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-adapter.html Tue Mar 10 21:03:25 2015 @@ -0,0 +1,140 @@ +<!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 - Apache Felix Dependency Manager - Adapter</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> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/subprojects.html">Apache Felix Subproject Documentation</a> » <a href="/documentation/subprojects/apache-felix-dependency-manager.html">Apache Felix Dependency Manager 4</a> + </div> + + + + <h1>Apache Felix Dependency Manager - Adapter</h1> + <h1 id="adapters">Adapters</h1> +<p>Adapters, like <a href="component-aspect.html">aspects</a>, are used to "extend" existing services, and can publish different services based on the existing one. An example would be implementing a management interface.</p> +<p>An adapter will be applied to any service that matches the specified interface and filter. For each matching service an adapter will be created based on the adapter implementation class. The adapter will be registered with the specified interface and existing properties from the original service plus any extra properties you supply here. It will also inherit all dependencies, and if you declare the original service as a member it will be injected.</p> +<p>An example:</p> +<div class="codehilite"><pre><span class="n">manager</span><span class="p">.</span><span class="n">createAdapterService</span><span class="p">(</span><span class="n">AdapteeService</span><span class="p">.</span><span class="n">class</span><span class="p">,</span> "<span class="p">(</span><span class="n">foo</span><span class="p">=</span><span class="n">bar</span><span class="p">)</span>"<span class="p">)</span> + <span class="p">.</span><span class="n">setInterface</span><span class="p">(</span><span class="n">AdapterService</span><span class="p">.</span><span class="n">class</span><span class="p">,</span> <span class="n">new</span> <span class="n">Hashtable</span><span class="p">()</span> <span class="p">)</span> + <span class="p">.</span><span class="n">setImplementation</span><span class="p">(</span><span class="n">AdapterImpl</span><span class="p">.</span><span class="n">class</span><span class="p">);</span> +</pre></div> + + +<h1 id="adapterservice">@AdapterService</h1> +<p>Adapters, like with <em>@AspectService</em>, are used to "extend" existing services, and can publish different services based on the existing one. When you annotate an adapter class with the <em>@AdapterService</em> +annotation, it will be applied to any service that matches the implemented +interface and filter. The adapter will be registered with the specified +interface and existing properties from the original service plus any extra +properties you supply here. If you declare the original service as a member +it will be injected. </p> +<h2 id="annotation-attributes">Annotation attributes:</h2> +<hr /> +<p><strong><code>adapteeService</code></strong> <br /> +<em>Required</em>: True <br /> +<em>Default</em>: --</p> +<p>Sets the adaptee service interface this adapter is applying to.</p> +<hr /> +<p><strong><code>provides</code></strong> <br /> +<em>Required</em>: False <br /> +<em>Default</em>: all directly implemented interfaces.</p> +<p>Sets the adapter service interface(s). By default, the directly implemented +interface(s) is (are) used. </p> +<hr /> +<p><strong><code>properties</code></strong> <br /> +<em>Required</em>: False <br /> +<em>Default</em>: All inherited adaptee service properties.</p> +<p>Sets some additional properties to use with the adapter service registration. +By default, the adapter will inherit all adaptee service properties.</p> +<hr /> +<p><strong><code>adapteeFilter</code></strong> <br /> +<em>Required</em>: False <br /> +<em>Default</em>: --</p> +<p>Sets the filter condition to use with the adapted service interface.</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 service implementation +instance. By default, the default constructor of the annotated class is used.</p> +<h2 id="usage-example">Usage example</h2> +<p>Here, the AdapterService is registered into the OSGI registry each time an AdapteeService is found from the registry. The AdapterImpl class adapts the AdapteeService to the AdapterService. The AdapterService will also have a service property (param=value), and will also include eventual service properties found from the AdapteeService:</p> +<div class="codehilite"><pre> <span class="p">@</span><span class="n">AdapterService</span><span class="p">(</span><span class="n">adapteeService</span> <span class="p">=</span> <span class="n">AdapteeService</span><span class="p">.</span><span class="n">class</span><span class="p">,</span> <span class="k">properties</span><span class="p">={@</span><span class="n">Property</span><span class="p">(</span><span class="n">name</span><span class="p">=</span>"<span class="n">param</span>"<span class="p">,</span> <span class="n">value</span><span class="p">=</span>"<span class="n">value</span>"<span class="p">)})</span> + <span class="n">class</span> <span class="n">AdapterImpl</span> <span class="n">implements</span> <span class="n">AdapterService</span> <span class="p">{</span> + <span class="o">//</span> <span class="n">The</span> <span class="n">service</span> <span class="n">we</span> <span class="n">are</span> <span class="n">adapting</span> <span class="p">(</span><span class="n">injected</span> <span class="n">by</span> <span class="n">reflection</span><span class="p">)</span> + <span class="n">protected</span> <span class="n">AdapteeService</span> <span class="n">adaptee</span><span class="p">;</span> + + <span class="n">public</span> <span class="n">void</span> <span class="n">doWork</span><span class="p">()</span> <span class="p">{</span> + <span class="n">adaptee</span><span class="p">.</span><span class="n">mehod1</span><span class="p">();</span> + <span class="n">adaptee</span><span class="p">.</span><span class="n">method2</span><span class="p">();</span> + <span class="p">}</span> + <span class="p">}</span> +</pre></div> + <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;"> + Rev. 1665276 by marrs on Mon, 9 Mar 2015 16:07:24 +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> Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-aspect.html ============================================================================== --- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-aspect.html (added) +++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-aspect.html Tue Mar 10 21:03:25 2015 @@ -0,0 +1,136 @@ +<!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 - Apache Felix Dependency Manager - Aspect</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> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/subprojects.html">Apache Felix Subproject Documentation</a> » <a href="/documentation/subprojects/apache-felix-dependency-manager.html">Apache Felix Dependency Manager 4</a> + </div> + + + + <h1>Apache Felix Dependency Manager - Aspect</h1> + <h1 id="aspects">Aspects</h1> +<p>Aspects, as part of aspect oriented programming, can be used in a dynamic environment such as OSGi to "extend" existing services and add certain "capabilities" to them. Examples of these are adding a specific caching mechanism to a storage service or implementing logging. Aspects in OSGi can be applied to services and can be added and removed at runtime.</p> +<p>Aspects allow you to define an "interceptor", or chain of interceptors for a service to add features like caching or logging, etc. An aspect will be applied to any service that matches the specified interface and filter. For each matching service an aspect will be created based on the aspect implementation class. The aspect will be registered with the same interface and properties as the original service, plus any extra properties you supply here. It will also inherit all dependencies, and if you declare the original service as a member it will be injected.</p> +<h1 id="aspectservice">@AspectService</h1> +<p>The <em>@AspectService</em> annotation allows you to create an aspect service. It supports the following attributes mentioned below.</p> +<h2 id="annotation-attributes">Annotation attributes</h2> +<hr /> +<p><strong><code>ranking</code></strong> <br /> +<em>Required</em>: No <br /> +<em>Default</em>: -- </p> +<p>Sets the ranking of this aspect. Since aspects are chained, the ranking +defines the order in which they are chained. Chain ranking is implemented as +a service ranking so service lookups automatically retrieve the top of the +chain.</p> +<hr /> +<p><strong><code>service</code></strong> <br /> +<em>Required</em>: No <br /> +<em>Default</em>: all directly implemented interfaces. </p> +<p>Sets the service interface to apply the aspect to. By default, the directly +implemented interface is used.</p> +<hr /> +<p><strong><code>filter</code></strong> <br /> +<em>Required</em>: No <br /> +<em>Default</em>: --</p> +<p>Sets the filter condition to use with the service interface this aspect is +applying to.</p> +<hr /> +<p><strong><code>properties</code></strong> <br /> +<em>Required</em>: No <br /> +<em>Default</em>: --</p> +<p>Sets Additional properties to use with the aspect service registration.</p> +<hr /> +<p><strong><code>field</code></strong> <br /> +<em>Required</em>: No <br /> +<em>Default</em>: --</p> +<p>Sets the field name where to inject the original service. By default, the original service is injected in any attributes in the aspect implementation that are of the same type as the aspect interface.</p> +<hr /> +<p><strong><code>factoryMethod</code></strong> <br /> +<em>Required</em>: No <br /> +<em>Default</em>: --</p> +<p>Sets the static method used to create the aspect service implementation +instance. The default constructor of the annotated class is used. +The factoryMethod can be used to provide a specific aspect implements, +like a DynamicProxy.</p> +<h2 id="usage-example">Usage example:</h2> +<div class="codehilite"><pre> <span class="p">@</span><span class="n">AspectService</span><span class="p">(</span><span class="n">ranking</span><span class="p">=</span>10<span class="p">),</span> <span class="k">properties</span><span class="p">={@</span><span class="n">Property</span><span class="p">(</span><span class="n">name</span><span class="p">=</span>"<span class="n">param</span>"<span class="p">,</span> <span class="n">value</span><span class="p">=</span>"<span class="n">value</span>"<span class="p">)})</span> + <span class="n">class</span> <span class="n">AspectService</span> <span class="n">implements</span> <span class="n">InterceptedService</span> <span class="p">{</span> + <span class="o">//</span> <span class="n">The</span> <span class="n">service</span> <span class="n">we</span> <span class="n">are</span> <span class="n">intercepting</span> <span class="p">(</span><span class="n">injected</span> <span class="n">by</span> <span class="n">reflection</span><span class="p">)</span> + <span class="n">protected</span> <span class="n">InterceptedService</span> <span class="n">intercepted</span><span class="p">;</span> + + <span class="n">public</span> <span class="n">void</span> <span class="n">doWork</span><span class="p">()</span> <span class="p">{</span> + <span class="n">intercepted</span><span class="p">.</span><span class="n">doWork</span><span class="p">();</span> + <span class="p">}</span> + <span class="p">}</span> +</pre></div> + <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;"> + Rev. 1665276 by marrs on Mon, 9 Mar 2015 16:07:24 +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> Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-bundle-adapter.html ============================================================================== --- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-bundle-adapter.html (added) +++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-bundle-adapter.html Tue Mar 10 21:03:25 2015 @@ -0,0 +1,151 @@ +<!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 - Apache Felix Dependency Manager - Bundle Adapter</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> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/subprojects.html">Apache Felix Subproject Documentation</a> » <a href="/documentation/subprojects/apache-felix-dependency-manager.html">Apache Felix Dependency Manager 4</a> + </div> + + + + <h1>Apache Felix Dependency Manager - Bundle Adapter</h1> + <h1 id="bundle-adapters">Bundle Adapters</h1> +<p>Bundle adapters are similar to AdapterService, but instead of adapting a +service, they adapt a bundle with a certain set of states (STARTED|INSTALLED|...), and provide a service on top of it.</p> +<p>The bundle adapter will be applied to any bundle that matches the specified +bundle state mask and filter conditions, which may match some of the bundle +OSGi manifest headers. For each matching bundle an adapter will be created +based on the adapter implementation class. The adapter will be registered +with the specified interface and with service properties found from the +original bundle OSGi manifest headers plus any extra properties you supply +here. If you declare the original bundle as a member it will be injected. </p> +<p>An example:</p> +<div class="codehilite"><pre><span class="n">manager</span><span class="p">.</span><span class="n">createBundleAdapterService</span><span class="p">(</span><span class="n">Bundle</span><span class="p">.</span><span class="n">INSTALLED</span> <span class="o">|</span> <span class="n">Bundle</span><span class="p">.</span><span class="n">RESOLVED</span> <span class="o">|</span> <span class="n">Bundle</span><span class="p">.</span><span class="n">ACTIVE</span><span class="p">,</span> + "<span class="p">(</span><span class="n">Bundle</span><span class="o">-</span><span class="n">SymbolicName</span><span class="p">=</span><span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">felix</span><span class="p">.</span><span class="n">dependencymanager</span><span class="p">)</span>"<span class="p">,</span> <span class="n">true</span><span class="p">)</span> + <span class="p">.</span><span class="n">setInterface</span><span class="p">(</span><span class="n">AdapterService</span><span class="p">.</span><span class="n">class</span><span class="p">.</span><span class="n">getName</span><span class="p">(),</span> <span class="n">new</span> <span class="n">Hashtable</span><span class="p">()</span> <span class="p">)</span> + <span class="p">.</span><span class="n">setImplementation</span><span class="p">(</span><span class="n">AdapterServiceImpl</span><span class="p">.</span><span class="n">class</span><span class="p">);</span> +</pre></div> + + +<h1 id="bundleadapterservice">@BundleAdapterService</h1> +<p>The following attributes are supported.</p> +<h2 id="annotation-attributes">Annotation attributes:</h2> +<hr /> +<p><strong><code>filter</code></strong> <br /> +<em>Required</em>: False <br /> +<em>Default</em>: --</p> +<p>The filter used to match some OSGi manifest headers from a given bundle.</p> +<hr /> +<p><strong><code>provides</code></strong> <br /> +<em>Required</em>: False <br /> +<em>Default</em>: all directly implemented interfaces.</p> +<p>The interface(s) to use when registering adapters. +By default, the interface(s) directly implemented by the annotated class is (are) used.</p> +<hr /> +<p><strong><code>properties</code></strong> <br /> +<em>Required</em>: False <br /> +<em>Default</em>: --</p> +<p>Additional properties to use with the service registration.</p> +<hr /> +<p><strong><code>stateMask</code></strong> <br /> +<em>Required</em>: False <br /> +<em>Default</em>: INSTALLED | RESOLVED | ACTIVE</p> +<p>The bundle state mask to apply. The mask is made up of the flags provided by +the org.osgi.framework.Bundle states +(UNINSTALLED | INSTALLED | RESOLVED | STARTING | STARTED | ACTIVE).</p> +<hr /> +<p><strong><code>propagate</code></strong> <br /> +<em>Required</em>: False <br /> +<em>Default</em>: true</p> +<p>Specifies if manifest headers from the bundle should be propagated to the +exposed service properties.</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 BundleAdapterService implementation +instance.</p> +<h2 id="usage-examples">Usage Examples</h2> +<p>In the following example, a "VideoPlayer" Service is registered into the OSGi registry each time an active bundle containing a "Video-Path" manifest header is detected:</p> +<div class="codehilite"><pre><span class="nd">@BundleAdapterService</span><span class="o">(</span><span class="n">filter</span> <span class="o">=</span> <span class="s">"(Video-Path=*)"</span><span class="o">,</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="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="n">Bundle</span> <span class="n">bundle</span><span class="o">;</span> <span class="c1">// Injected by reflection</span> + + <span class="kt">void</span> <span class="nf">play</span><span class="o">()</span> <span class="o">{</span> + <span class="n">URL</span> <span class="n">mpegFile</span> <span class="o">=</span> <span class="n">bundle</span><span class="o">.</span><span class="na">getEntry</span><span class="o">(</span><span class="n">bundle</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">"Video-Path"</span><span class="o">));</span> + <span class="c1">// play the video provided by the bundle ...</span> + <span class="o">}</span> + + <span class="kt">void</span> <span class="nf">stop</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. 1665276 by marrs on Mon, 9 Mar 2015 16:07:24 +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> Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-factory-configuration-adapter.html ============================================================================== --- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-factory-configuration-adapter.html (added) +++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-factory-configuration-adapter.html Tue Mar 10 21:03:25 2015 @@ -0,0 +1,226 @@ +<!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 - Apache Felix Dependency Manager - Factory Configuration Adapter Service</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> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/subprojects.html">Apache Felix Subproject Documentation</a> » <a href="/documentation/subprojects/apache-felix-dependency-manager.html">Apache Felix Dependency Manager 4</a> + </div> + + + + <h1>Apache Felix Dependency Manager - Factory Configuration Adapter Service</h1> + <h1 id="factory-configuration-adapter-service">Factory Configuration Adapter Service</h1> +<p>A factory configuration adapter service creates an adapter for each matching configuration in Configuration Admin. For each new factory configuration matching the factoryPid, an adapter will be created based on the adapter implementation class. 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. It will also inherit all dependencies.</p> +<p>Usage Example:</p> +<div class="codehilite"><pre><span class="n">manager</span><span class="p">.</span><span class="n">createFactoryConfigurationAdapterService</span><span class="p">(</span>"<span class="n">MyFactoryPid</span>"<span class="p">,</span> "<span class="n">update</span>"<span class="p">,</span> <span class="n">true</span><span class="p">)</span> + <span class="p">.</span><span class="n">setInterface</span><span class="p">(</span><span class="n">AdapterService</span><span class="p">.</span><span class="n">class</span><span class="p">.</span><span class="n">getName</span><span class="p">(),</span> <span class="n">new</span> <span class="n">Hashtable</span><span class="p">()</span> <span class="p">)</span> + <span class="p">.</span><span class="n">setImplementation</span><span class="p">(</span><span class="n">AdapterServiceImpl</span><span class="p">.</span><span class="n">class</span><span class="p">);</span> +</pre></div> + + +<h1 id="factoryconfigurationadapterservice">@FactoryConfigurationAdapterService</h1> +<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> +<h2 id="annotation-attributes">Annotation attributes:</h2> +<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>factoryClass</code></strong> <br /> +<em>Required</em>: False <br /> +<em>Default</em>: The class name, including the package.</p> +<p>Returns the factory pid from a class name. The full class name will be used as the +configuration PID. You can use this method when you use an interface annoted with +standard bndtols metatype annotations. (see http://www.aqute.biz/Bnd/MetaType).</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>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> +<h2 id="usage-examples">Usage Examples</h2> +<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">"DictionaryServiceFactory"</span><span class="o">,</span> <span class="n">updated</span><span class="o">=</span><span class="s">"updated"</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">"lang"</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">"words"</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"><</span><span class="n">String</span><span class="o">></span> <span class="n">m_words</span> <span class="o">=</span> <span class="k">new</span> <span class="n">CopyOnWriteArrayList</span><span class="o"><</span><span class="n">String</span><span class="o">>();</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"><</span><span class="n">String</span><span class="o">,</span> <span class="o">?></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 is the same example as above, but using meta types (the DM annotations metatype attributes are deprecated and +it's better to use standard bnd metatype annotations, the following example are using bnd metatypes):</p> +<p>First, we declare our factory configuration metadata using standard bndtools metatype annotations (see http://www.aqute.biz/Bnd/MetaType):</p> +<div class="codehilite"><pre><span class="kn">package</span> <span class="n">sample</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">java.util.List</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">aQute.bnd.annotation.metatype.Meta.AD</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">aQute.bnd.annotation.metatype.Meta.OCD</span><span class="o">;</span> + +<span class="nd">@OCD</span><span class="o">(</span><span class="n">factory</span> <span class="o">=</span> <span class="kc">true</span><span class="o">,</span> <span class="n">description</span> <span class="o">=</span> <span class="s">"Declare here some Dictionary instances."</span><span class="o">)</span> +<span class="kd">public</span> <span class="kd">interface</span> <span class="nc">DictionaryConfiguration</span> <span class="o">{</span> + <span class="nd">@AD</span><span class="o">(</span><span class="n">description</span> <span class="o">=</span> <span class="s">"Describes the dictionary language."</span><span class="o">,</span> <span class="n">deflt</span> <span class="o">=</span> <span class="s">"en"</span><span class="o">)</span> + <span class="n">String</span> <span class="nf">lang</span><span class="o">();</span> + + <span class="nd">@AD</span><span class="o">(</span><span class="n">description</span> <span class="o">=</span> <span class="s">"Declare here the list of words supported by this dictionary."</span><span class="o">)</span> + <span class="n">List</span> <span class="nf">words</span><span class="o">();</span> +<span class="o">}</span> +</pre></div> + + +<p>And here is the Dictionary service, and we instantiate our DictionaryConfiguration interface using the bndlib <em>Configurable</em> helper class.</p> +<div class="codehilite"><pre><span class="kn">import</span> <span class="nn">java.util.List</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">aQute.bnd.annotation.metatype.Configurable</span><span class="o">;</span> + +<span class="nd">@FactoryConfigurationAdapterService</span><span class="o">(</span><span class="n">factoryPidClass</span><span class="o">=</span><span class="n">DictionaryConfiguration</span><span class="o">.</span><span class="na">class</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="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"><</span><span class="n">String</span><span class="o">,</span> <span class="o">?></span> <span class="n">props</span><span class="o">)</span> <span class="o">{</span> + <span class="c1">// load configuration from the provided dictionary, or throw an exception of any configuration error.</span> + <span class="n">DictionaryConfiguration</span> <span class="n">cnf</span> <span class="o">=</span> <span class="n">Configurable</span><span class="o">.</span><span class="na">createConfigurable</span><span class="o">(</span><span class="n">DictionaryConfiguration</span><span class="o">.</span><span class="na">class</span><span class="o">,</span> <span class="n">props</span><span class="o">);</span> + + <span class="n">m_lang</span> <span class="o">=</span> <span class="n">config</span><span class="o">.</span><span class="na">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="k">for</span> <span class="o">(</span><span class="n">String</span> <span class="n">word</span> <span class="o">:</span> <span class="n">conf</span><span class="o">.</span><span class="na">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="o">...</span> +<span class="o">}</span> +</pre></div> + <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;"> + Rev. 1665276 by marrs on Mon, 9 Mar 2015 16:07:24 +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> Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-resource-adapter.html ============================================================================== --- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-resource-adapter.html (added) +++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-resource-adapter.html Tue Mar 10 21:03:25 2015 @@ -0,0 +1,124 @@ +<!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 - Apache Felix Dependency Manager - Resource Adapter</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> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/subprojects.html">Apache Felix Subproject Documentation</a> » <a href="/documentation/subprojects/apache-felix-dependency-manager.html">Apache Felix Dependency Manager 4</a> + </div> + + + + <h1>Apache Felix Dependency Manager - Resource Adapter</h1> + <h1 id="resource-adapters">Resource Adapters</h1> +<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> +<p>A resource adapter will be applied to any resource that matches the specified filter condition. 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 existing properties from the original resource plus any extra properties you supply here. It will also inherit all dependencies, and if you declare the original service as a member it will be injected.</p> +<p>Usage Example:</p> +<div class="codehilite"><pre><span class="n">manager</span><span class="p">.</span><span class="n">createResourceAdapterService</span><span class="p">(</span>"<span class="p">(</span><span class="o">&</span><span class="p">(</span><span class="n">path</span><span class="p">=</span><span class="o">/</span><span class="n">test</span><span class="p">)(</span><span class="n">repository</span><span class="p">=</span><span class="n">TestRepository</span><span class="p">))</span>"<span class="p">,</span> <span class="n">true</span><span class="p">)</span> + <span class="p">.</span><span class="n">setInterface</span><span class="p">(</span><span class="n">AdapterService</span><span class="p">.</span><span class="n">class</span><span class="p">.</span><span class="n">getName</span><span class="p">(),</span> <span class="n">new</span> <span class="n">Hashtable</span><span class="p">()</span> <span class="p">)</span> + <span class="p">.</span><span class="n">setImplementation</span><span class="p">(</span><span class="n">AdapterServiceImpl</span><span class="p">.</span><span class="n">class</span><span class="p">);</span> +</pre></div> + + +<h1 id="resourceadapterservice">@ResourceAdapterService</h1> +<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> +<h2 id="annotation-attributes">Annotation attributes</h2> +<p>TBD</p> +<h2 id="usage-examples">Usage Examples:</h2> +<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">"(&(path=/videos/*.mkv)(host=localhost))"</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. 1665276 by marrs on Mon, 9 Mar 2015 16:07:24 +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> Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-singleton.html ============================================================================== --- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-singleton.html (added) +++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-singleton.html Tue Mar 10 21:03:25 2015 @@ -0,0 +1,245 @@ +<!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 - Apache Felix Dependency Manager - Singleton Component</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> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/subprojects.html">Apache Felix Subproject Documentation</a> » <a href="/documentation/subprojects/apache-felix-dependency-manager.html">Apache Felix Dependency Manager 4</a> + </div> + + + + <h1>Apache Felix Dependency Manager - Singleton Component</h1> + <h1 id="component">Component</h1> +<p>Components are the main building blocks for OSGi applications. They can publish themselves as a service, and they can have dependencies. These dependencies will influence their life cycle as component will only be activated when all required dependencies are available.</p> +<p>Usage example:</p> +<div class="codehilite"><pre><span class="n">dm</span><span class="p">.</span><span class="n">add</span><span class="p">(</span><span class="n">createComponent</span><span class="p">()</span> + <span class="p">.</span><span class="n">setInterface</span><span class="p">(</span><span class="n">TranslationService</span><span class="p">.</span><span class="n">class</span><span class="p">.</span><span class="n">getName</span><span class="p">(),</span> <span class="n">null</span><span class="p">)</span> + <span class="p">.</span><span class="n">setImplementation</span><span class="p">(</span><span class="n">GoogleBasedTranslationService</span><span class="p">.</span><span class="n">class</span><span class="p">)</span> + <span class="p">.</span><span class="n">add</span><span class="p">(</span><span class="n">createServiceDependency</span><span class="p">()</span> + <span class="p">.</span><span class="n">setService</span><span class="p">(</span><span class="n">LocalizationService</span><span class="p">.</span><span class="n">class</span><span class="p">,</span> "<span class="p">(</span><span class="n">language</span><span class="p">=</span><span class="n">en</span><span class="p">)</span>"<span class="p">)</span> + <span class="p">.</span><span class="n">setRequired</span><span class="p">(</span><span class="n">true</span><span class="p">)</span> + <span class="p">)</span> + <span class="p">.</span><span class="n">add</span><span class="p">(</span><span class="n">createServiceDependency</span><span class="p">()</span> + <span class="p">.</span><span class="n">setService</span><span class="p">(</span><span class="n">LogService</span><span class="p">.</span><span class="n">class</span><span class="p">)</span> + <span class="p">.</span><span class="n">setRequired</span><span class="p">(</span><span class="n">false</span><span class="p">)</span> + <span class="p">)</span> +<span class="p">);</span> +</pre></div> + + +<h1 id="component_1">@Component</h1> +<p>This annotation annotates an implementation class that optionally publishes +an OSGi service, and optionally has some dependencies, with a managed +lifecycle. </p> +<h2 id="annotation-attributes">Annotation attributes</h2> +<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>factoryName</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 factoryName can be +used. When you use this attribute, a <em>org.apache.felix.dm.runtime.api.ComponentFactory</em> +OSGi Service will be provided with a <em>dm.factory.name</em> service property matching your +specified factoryName attribute. The ComponentFactory will be provided once the +component bundle is started, even if required dependencies are not available, +and the ComponentFactory will be unregistered from the OSGi registry once the component +bundle is stopped or disposed using the <em>ComponentInstance.dispose()</em> method.</p> +<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 <em>factoryName</em> 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">"MyPid"</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 factoryName, where the X component is instantiated/updated/disposed by another Y component:</p> +<div class="codehilite"><pre> <span class="kn">import</span> <span class="nn">org.apache.felix.dm.runtime.api.ComponentFactory</span><span class="o">;</span> + <span class="kn">import</span> <span class="nn">org.apache.felix.dm.runtime.api.ComponentInstance</span><span class="o">;</span> + + <span class="nd">@Component</span><span class="o">(</span><span class="n">factoryName</span><span class="o">=</span><span class="s">"MyComponentFactory"</span><span class="o">,</span> <span class="n">factoryConfigure</span><span class="o">=</span><span class="s">"configure"</span><span class="o">)</span> + <span class="kd">class</span> <span class="nc">X</span> <span class="kd">implements</span> <span class="n">Z</span> <span class="o">{</span> + <span class="kt">void</span> <span class="nf">configure</span><span class="o">(</span><span class="n">Dictionary</span> <span class="n">conf</span><span class="o">)</span> <span class="o">{</span> + <span class="c1">// Configure or reconfigure our component. The conf is provided by </span> + <span class="c1">// the factory, and all public properties (which don't</span> + <span class="c1">// start with a dot) are propagated with the Service</span> + <span class="c1">// properties eventually specified in the properties</span> + <span class="c1">// annotation attribute.</span> + <span class="o">}</span> + + <span class="nd">@ServiceDependency</span> + <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</span> + <span class="c1">// in the OSGi registry as a Z service.</span> + <span class="o">}</span> + + <span class="kd">public</span> <span class="kt">void</span> <span class="nf">doService</span><span class="o">()</span> <span class="o">{</span> + <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="c1">// This Set acts as a Factory API for creating X component instances.</span> + <span class="nd">@ServiceDependency</span><span class="o">(</span><span class="n">filter</span><span class="o">=</span><span class="s">"(dm.factory.name=MyComponentFactory)"</span><span class="o">)</span> + <span class="n">ComponentFactory</span> <span class="n">_XFactory</span><span class="o">;</span> + + <span class="nd">@Start</span> + <span class="kt">void</span> <span class="nf">start</span><span class="o">()</span> <span class="o">{</span> + <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">ComponentInstance</span> <span class="n">i1</span> <span class="o">=</span> <span class="n">_XFactory</span><span class="o">.</span><span class="na">newInstance</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">ComponentInstance</span> <span class="n">i2</span> <span class="o">=</span> <span class="n">_XFactory</span><span class="o">.</span><span class="na">newInstance</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="k">new</span> <span class="n">Hashtable</span><span class="o">()</span> <span class="o">;</span> + <span class="n">i1</span><span class="o">.</span><span class="na">update</span><span class="o">(</span><span class="n">x1</span><span class="o">);</span> + + <span class="c1">// Destroy components</span> + <span class="n">i1</span><span class="o">.</span><span class="na">dispose</span><span class="o">();</span> + <span class="n">i2</span><span class="o">.</span><span class="na">dispose</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. 1665276 by marrs on Mon, 9 Mar 2015 16:07:24 +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>
