Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/components.html ============================================================================== --- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/components.html (added) +++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/components.html Tue Mar 10 21:03:25 2015 @@ -0,0 +1,117 @@ +<!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 - Components</title> + <link rel="icon" href="/res/favicon.ico"> + <link rel="stylesheet" href="/res/site.css" type="text/css" media="all"> + <link rel="stylesheet" href="/res/codehilite.css" type="text/css" media="all"> + <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 - Components</h1> + <p>Components are declared by the dependency manager and can be implemented by POJOs that contain no references to the OSGi framework whatsoever. Components are the main building blocks of your OSGi application. They have a life cycle, can register themselves as services and have zero or more dependencies.</p> +<p>You can either use the Java API or the Java Annotations and this reference section describes both.</p> +<h1 id="types-of-components">Types of Components</h1> +<p>There are different types of Dependency Manager components:</p> +<ul> +<li><a href="component-singleton.html"><em>Component</em></a>: Components are the main building blocks for OSGi applications. They can publish themselves as a service, and/or they can have dependencies. These dependencies will influence their life cycle as component will only be activated when all required dependencies are available.</li> +<li><a href="component-aspect.html"><em>Aspect Service</em></a>: A service that provides a non-functional aspect on top of an existing service. In aspect oriented programming, an aspect, or interceptor can sit between a client and another target service used by the client. An Aspect Service first tracks a target service and is created once the target service is detected. Then the Aspect Service is provided, but with a higher ranking, and the client is transparently updated with the aspect. Aspects can be chained and may apply to the same target service (and in this case, the ranking of the Aspect service is used to chain aspects in the proper order).</li> +<li><a href="component-adapter.html"><em>Adapter Service</em></a>: A Service that adapts another existing service into a new one. Like with aspects, sometimes you want to create adapters for certain services, which add certain behavior that results in the publication of (in this case) a different service. Adapters can dynamically be added and removed and allow you to keep your basic services implementations clean and simple, adding extra features on top of them in a modular way.</li> +<li><a href="component-bundle-adapter.html"><em>Bundle Adapter Service</em></a>: creates an OSGi service a service on top of a given bundle.</li> +<li><a href="component-resource-adapter.html"><em>Resource Adapter Service</em></a>: creates an OSGi service on top of a specific Resource.</li> +<li><a href="component-factory-configuration-adapter.html"><em>Factory Configuration Adapter Service</em></a>: creates an OSGi service from ConfigAdmin, using a factoryPid, and a ManagedServiceFactory.</li> +</ul> +<h1 id="life-cycle">Life cycle</h1> +<p>The dependency manager, as part of a bundle, shares the generic bundle life cycle explained in the OSGi specification. The life cycle of the dependency manager itself, and the components it manages, can be located inside the <em>active</em> state of the hosting bundle.</p> +<p>Each component you define gets its own life cycle, which is explained in the state diagram below.</p> +<p><img src="./diagrams/statediagram.png" alt="State diagram" style="width: 430px"/></p> +<p>A component is associated with an instance. This instance can either be specified directly, or you can specify its class. If you do the latter, the actual instance will be created lazily. </p> +<p>Changes in the state of the component will trigger the following life cycle methods:</p> +<ul> +<li><code>init</code>, </li> +<li><code>start</code>, </li> +<li><code>stop</code> and </li> +<li><code>destroy</code>.</li> +</ul> +<p>The dependency manager will look for methods with these names and one of the following signatures in this order:</p> +<ul> +<li><code>(Component)</code>,</li> +<li><code>()</code>.</li> +</ul> +<p>If you don't specify anything, the methods with these names will be invoked on the instance. By using <code>setCallbacks()</code> you can however change this behavior: You can change the names of the methods to look for. Any methods that are set to <code>null</code> will not be invoked at all. Another thing you can do is to specify a different instance to invoke these methods on. If you do that, you will usually want to use the first signature, which gives you a reference to the <code>Component</code> whose life cycle method was invoked.</p> +<h1 id="interfaces-and-properties">Interfaces and properties</h1> +<p>Components in the context of the dependency manager can be published as OSGi services under one or more interface names, plus optionally a set of properties. This is no different than a normal OSGi service. It's important to mention that you don't have to register a service. If you don't, you basically created a component that can do work and have dependencies and a managed life cycle.</p> +<h1 id="composition">Composition</h1> +<p>When implementing more complex components, you often find yourself using more than one instance. However, several of these instances might want to have dependencies injected. In such cases you need to tell the dependency manager which instances to consider. This has to be a fixed set of instances however.</p> +<h1 id="factories">Factories</h1> +<p>Out of the box, there already is support for lazy instantiation, meaning that the dependency manager can create component instances for you when their required dependencies are resolved. However, sometimes creating a single instance using a default constructor is not enough. In those cases, you can tell the dependency manager to delegate the creation process to a factory.</p> + <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;"> + Rev. 1665351 by uiterlix on Mon, 9 Mar 2015 20:43:39 +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/dependencies.html ============================================================================== --- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependencies.html (added) +++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependencies.html Tue Mar 10 21:03:25 2015 @@ -0,0 +1,102 @@ +<!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 - Dependencies</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 - Dependencies</h1> + <h1 id="dependencies">Dependencies</h1> +<p>The dependency manager supports many different types of dependencies, all of which can be required or optional. A dependency can be added to one or more components and it is possible to add them dynamically (even from within the component itself if necessary, which allows for some really dynamic dependency configuration).</p> +<h2 id="injection">Injection</h2> +<p>One way to deal with dependencies is to have them injected into your component instances automatically. All you need to do is simply declare a field of the same type as your dependency, make the member volatile so any changes will become visible immediately and you're done. If a dependency is optional, a null object will be injected if the dependency is not available.</p> +<p>Sometimes you need more control over injection, so optionally you can even specify the name of the field to inject into. This allows you to depend on different dependencies of the same type, or simply to prevent injection into more than one field.</p> +<h2 id="callbacks">Callbacks</h2> +<p>When keeping track of multiple instances of a dependency, or when you simply want something to happen whenever a dependency becomes (un)available or changes, you can define callbacks, like <code>added</code>, <code>changed</code> and <code>removed</code>. Optionally, you can provide the dependency manager with an instance to invoke these callback methods on. If you don't, they'll be invoked on the component instance.</p> +<h2 id="types-of-dependencies">Types of Dependencies</h2> +<p>Out of the box, several types of dependencies are supported:</p> +<ul> +<li><a href="dependency-service.html">Service</a></li> +<li><a href="dependency-configuration.html">Configuration</a></li> +<li><a href="dependency-bundle.html">Bundle</a></li> +<li><a href="dependency-resource.html">Resource</a></li> +</ul> +<p>However, it's quite easy to add your own custom type of dependency too, as is described below.</p> +<h2 id="implementing-your-own-dependency">Implementing Your Own Dependency</h2> +<p>All dependencies share a common API which you can implement yourself if you need a special type of dependency. Whilst not entirely trivial, this allows you to create your own types of dependencies. This can be useful for various scenarios where you want to have components that depend on things that are not services, bundles or configuration.</p> +<p>An example implementation can be found in the samples available in the source distribution. +In the org.apache.felix.dependencymanager.samples module, you can refer to src/org/apache/felix/dependencymanager/samples/customdep/README file, +which describes a custom "PathDependency" that tracks files that are added or removed from /tmp/ directory.</p> + <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/dependency-bundle.html ============================================================================== --- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-bundle.html (added) +++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-bundle.html Tue Mar 10 21:03:25 2015 @@ -0,0 +1,114 @@ +<!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 Dependency</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 Dependency</h1> + <h1 id="bundle-dependency">Bundle Dependency</h1> +<p>A bundle dependency allows you to depend on a bundle in a certain set of states, as indicated by a state mask. You can also use a filter condition that is matched against all manifest entries. Finally you can provide a reference to an existing bundle.</p> +<h1 id="bundledependency">@BundleDependency</h1> +<p>A bundle dependency allows you to depend on a bundle in a certain set of states (INSTALLED\|RESOLVED\|STARTED\|...), as indicated by a state mask. You can also use a filter condition that is matched against all manifest entries. When applied on a class field, optional unavailable dependencies are injected with a NullObject.</p> +<p>Attributes:</p> +<ul> +<li><em>changed</em>: Returns the callback method to be invoked when the service have changed.</li> +<li><em>removed</em>: Returns the callback method to invoke when the service is lost.</li> +<li><em>required</em>: Returns whether the dependency is required or not.</li> +<li><em>filter</em>: Returns the filter dependency</li> +<li><em>stateMask</em>: Returns the bundle state mask (Bundle.INSTALLED \| Bundle.ACTIVE etc ...).</li> +<li><em>propagate</em>: Specifies if the manifest headers from the bundle should be propagated to the service properties.</li> +<li><em>name</em>: The name used when dynamically configuring this dependency from the init method. Specifying this attribute allows to dynamically configure the dependency filter and required flag from the Service's init method. All unnamed dependencies will be injected before the init() method; so from the init() method, you can then pick up whatever information needed from already injected (unnamed) dependencies, and configure dynamically your named dependencies, which will then be calculated once the init() method returns. +Please refer to <a href="">Here</a>.</li> +</ul> +<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">"unloadServiceComponents"</span><span class="o">,</span> + <span class="n">filter</span> <span class="o">=</span> <span class="s">"(Service-Component=*)"</span> + <span class="n">stateMask</span> <span class="o">=</span> <span class="n">Bundle</span><span class="o">.</span><span class="na">ACTIVE</span><span class="o">)</span> + <span class="kt">void</span> <span class="nf">loadServiceComponents</span><span class="o">(</span><span class="n">Bundle</span> <span class="n">b</span><span class="o">)</span> <span class="o">{</span> + <span class="n">String</span> <span class="n">descriptorPaths</span> <span class="o">=</span> <span class="o">(</span><span class="n">String</span><span class="o">)</span> <span class="n">b</span><span class="o">.</span><span class="na">getHeaders</span><span class="o">().</span><span class="na">get</span><span class="o">(</span><span class="s">"Service-Component"</span><span class="o">);</span> + <span class="c1">// load all service component specified in the XML descriptorPaths files ...</span> + <span class="o">}</span> + + <span class="kt">void</span> <span class="nf">unloadServiceComponents</span><span class="o">(</span><span class="n">Bundle</span> <span class="n">b</span><span class="o">)</span> <span class="o">{</span> + <span class="c1">// unload all service component we loaded from our "loadServiceComponents" method.</span> + <span class="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/dependency-configuration.html ============================================================================== --- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-configuration.html (added) +++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-configuration.html Tue Mar 10 21:03:25 2015 @@ -0,0 +1,194 @@ +<!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 - Configuration Dependency</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 - Configuration Dependency</h1> + <h1 id="configuration-dependency">Configuration Dependency</h1> +<p>A configuration dependency is always required, and allows you to depend on the availability of a valid configuration for your component. Optional configuration dependencies are not supported because in that case you can just as well register as a <code>ManagedService</code> yourself.</p> +<h2 id="configurationdependency">@ConfigurationDependency</h2> +<p>A configuration dependency is always required, and allows you to depend on the availability of a valid configuration for your component. This dependency requires the OSGi Configuration Admin Service.</p> +<p>Annotation attributes:</p> +<ul> +<li><em>pid</em>: Returns the pid for a given service (by default, the pid is the service class name).</li> +<li><em>pidClass</em>: Will the the name of the specified class as the 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>name</em>: The name for this configuration dependency. When you give a name a dependency, it won't be evaluated immediately, but after the component's init method has been called, +and from the init method, you can then return a map in order to dynamically configure the +configuration dependency (the map has to contain a "pid" and/or "propagate" flag, prefixed +with the dependency name). Then the dependency will be evaluated after the component init +method, and will be injected before the start method. </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 ... +(we use here standard bnd metatype annotations, <a href="http://www.aqute.biz/Bnd/MetaType";>see bnd metatype documentation here</a>.</p> +<p>First, we define the configuration metadata, using standard bndtools metatatype annotations:</p> +<div class="codehilite"><pre> <span class="p">:::</span><span class="n">java</span> + <span class="n">package</span> <span class="n">sample</span><span class="p">;</span> + <span class="n">import</span> <span class="n">aQute</span><span class="p">.</span><span class="n">bnd</span><span class="p">.</span><span class="n">annotation</span><span class="p">.</span><span class="n">metatype</span><span class="p">.</span><span class="n">Meta</span><span class="p">.</span><span class="n">AD</span><span class="p">;</span> + <span class="n">import</span> <span class="n">aQute</span><span class="p">.</span><span class="n">bnd</span><span class="p">.</span><span class="n">annotation</span><span class="p">.</span><span class="n">metatype</span><span class="p">.</span><span class="n">Meta</span><span class="p">.</span><span class="n">OCD</span><span class="p">;</span> + + <span class="p">@</span><span class="n">OCD</span><span class="p">(</span><span class="n">description</span> <span class="p">=</span> "<span class="n">Declare</span> <span class="n">here</span> <span class="n">the</span> <span class="n">Printer</span> <span class="n">Configuration</span><span class="p">.</span>"<span class="p">)</span> + <span class="n">public</span> <span class="n">interface</span> <span class="n">PrinterConfiguration</span> <span class="p">{</span> + <span class="p">@</span><span class="n">AD</span><span class="p">(</span><span class="n">description</span> <span class="p">=</span> "<span class="n">Enter</span> <span class="n">the</span> <span class="n">printer</span> <span class="n">ip</span> <span class="n">address</span>"<span class="p">)</span> + <span class="n">String</span> <span class="n">ipAddress</span><span class="p">();</span> + + <span class="p">@</span><span class="n">AD</span><span class="p">(</span><span class="n">description</span> <span class="p">=</span> "<span class="n">Enter</span> <span class="n">the</span> <span class="n">printer</span> <span class="n">address</span> <span class="n">port</span> <span class="n">number</span><span class="p">.</span>"<span class="p">)</span> + <span class="n">int</span> <span class="n">portNumber</span><span class="p">();</span> + <span class="p">}</span> +</pre></div> + + +<p>Next, we define our Printer service which instantiates the PrinterConfiguration using the *Configurable" bndlib helper:</p> +<div class="codehilite"><pre> <span class="p">:::</span><span class="n">java</span> + <span class="n">package</span> <span class="n">sample</span><span class="p">;</span> + <span class="n">import</span> <span class="n">aQute</span><span class="p">.</span><span class="n">bnd</span><span class="p">.</span><span class="n">annotation</span><span class="p">.</span><span class="n">metatype</span><span class="o">.*</span><span class="p">;</span> + + <span class="p">@</span><span class="n">Component</span> + <span class="n">public</span> <span class="n">class</span> <span class="n">Printer</span> <span class="p">{</span> + <span class="p">@</span><span class="n">ConfigurationDependency</span><span class="p">(</span><span class="n">pidClass</span> <span class="p">=</span> <span class="n">PrinterConfiguration</span><span class="p">.</span><span class="n">class</span><span class="p">)</span> <span class="o">//</span> <span class="n">Will</span> <span class="n">use</span> <span class="n">pid</span> "<span class="n">sample</span><span class="p">.</span><span class="n">PrinterConfiguration</span>" + <span class="n">void</span> <span class="n">updated</span><span class="p">(</span><span class="n">Dictionary</span> <span class="n">props</span><span class="p">)</span> <span class="p">{</span> + <span class="o">//</span> <span class="n">load</span> <span class="n">configuration</span> <span class="n">from</span> <span class="n">the</span> <span class="n">provided</span> <span class="n">dictionary</span><span class="p">,</span> <span class="n">or</span> <span class="n">throw</span> <span class="n">an</span> <span class="n">exception</span> <span class="n">of</span> <span class="n">any</span> <span class="n">configuration</span> <span class="n">error</span><span class="p">.</span> + <span class="n">PrinterConfig</span> <span class="n">cnf</span> <span class="p">=</span> <span class="n">Configurable</span><span class="p">.</span><span class="n">createConfigurable</span><span class="p">(</span><span class="n">PrinterConfig</span><span class="p">.</span><span class="n">class</span><span class="p">,</span> <span class="n">props</span><span class="p">);</span> + <span class="n">String</span> <span class="n">ip</span> <span class="p">=</span> <span class="n">cnf</span><span class="p">.</span><span class="n">ipAddress</span><span class="p">();</span> + <span class="n">int</span> <span class="n">port</span> <span class="p">=</span> <span class="n">cnf</span><span class="p">.</span><span class="n">portNumber</span><span class="p">();</span> + <span class="p">...</span> + <span class="p">}</span> + <span class="p">}</span> +</pre></div> + + +<p>Finally, the last example shows how to dynamically configure a configuration dependency pid from the init method. +The following component first depends on a "sample.MyComponent" configuration pid. Then the init method gets from that configuration +another pid for a second "global" configuration:</p> +<div class="codehilite"><pre><span class="kn">package</span> <span class="n">sample</span><span class="o">;</span> + +<span class="cm">/**</span> +<span class="cm"> * A Service that dynamically defines an extra dynamic configuration dependency from its init method. </span> +<span class="cm"> */</span> +<span class="nd">@Component</span> +<span class="kd">class</span> <span class="nc">MyComponent</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="c1">// Inject initial Configuration (injected before any other required dependencies)</span> + <span class="nd">@ConfigurationDependency</span> + <span class="kt">void</span> <span class="nf">componentConfiguration</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">// you must throw an exception if the configuration is not valid</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 our dynamic configuration whose dependency name is "global".</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="n">Map</span> <span class="n">properties</span> <span class="o">=</span> <span class="k">new</span> <span class="n">HashMap</span><span class="o">();</span> + <span class="n">properties</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"global.pid"</span><span class="o">,</span> <span class="n">m_config</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">"globalConfig.pid"</span><span class="o">));</span> + <span class="n">properties</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"global.propagate"</span><span class="o">,</span> <span class="n">m_config</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">"globalConfig.propagate"</span><span class="o">));</span> + <span class="k">return</span> <span class="n">properties</span><span class="o">;</span> + <span class="o">}</span> + + <span class="c1">// Injected after init, and dynamically configured by the init method.</span> + <span class="nd">@ConfigurationDependency</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="s">"global"</span><span class="o">)</span> + <span class="kt">void</span> <span class="nf">globalConfiguration</span><span class="o">(</span><span class="n">Dictionary</span> <span class="n">globalConfig</span><span class="o">)</span> <span class="o">{</span> + <span class="c1">// you must throw an exception if the configuration is not valid</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"> */</span> + <span class="nd">@Start</span> + <span class="kt">void</span> <span class="nf">start</span><span class="o">()</span> <span class="o">{</span> + <span class="o">}</span> +<span class="o">}</span> +</pre></div> + <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;"> + Rev. 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/dependency-resource.html ============================================================================== --- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-resource.html (added) +++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-resource.html Tue Mar 10 21:03:25 2015 @@ -0,0 +1,161 @@ +<!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 Dependency</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 Dependency</h1> + <h1 id="resource-dependency">Resource Dependency</h1> +<p>A resource dependency allows you to depend on a resource. A resource is a URL and you can use a filter condition based on protocol, host, port, path and URL.</p> +<h1 id="resourcedependency">@ResourceDependency</h1> +<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="">Here</a>.</li> +</ul> +<p>Usage Examples +Here, the "VideoPlayer" component plays any provided MKV video resources</p> +<div class="codehilite"><pre><span class="nd">@Component</span> +<span class="kd">public</span> <span class="kd">class</span> <span class="nc">VideoPlayer</span> <span class="o">{</span> + <span class="nd">@ResourceDependency</span><span class="o">(</span><span class="n">required</span><span class="o">=</span><span class="kc">false</span><span class="o">,</span> <span class="n">filter</span><span class="o">=</span><span class="s">"(path=/videos/*.mkv)"</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"><</span><span class="n">ResourceHandler</span><span class="o">,</span> <span class="n">Filter</span><span class="o">></span> <span class="n">m_handlers</span> <span class="o">=</span> <span class="k">new</span> <span class="n">HashMap</span><span class="o"><</span><span class="n">ResourceHandler</span><span class="o">,</span> <span class="n">Filter</span><span class="o">>();</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">"http://localhost:8080/videos/video1.mkv"</span><span class="o">),</span> + <span class="k">new</span> <span class="nf">URL</span><span class="o">(</span><span class="s">"http://localhost:8080/videos/video2.mkv"</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"><</span><span class="n">String</span><span class="o">,</span> <span class="n">String</span><span class="o">></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">"filter"</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">"(path=*)"</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. 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/dependency-service.html ============================================================================== --- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-service.html (added) +++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-service.html Tue Mar 10 21:03:25 2015 @@ -0,0 +1,150 @@ +<!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 - Service Dependency</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 - Service Dependency</h1> + <h1 id="service-dependency">Service Dependency</h1> +<p>A service dependency allows you to depend on a service, either by type or by using an additional filter condition. You can even depend on an existing service directly by providing a reference to it.</p> +<h1 id="servicedependency">@ServiceDependency</h1> +<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 > -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="">Here</a> for more informations about named dependencies.</li> +<li><em>propagate</em>: Returns true if the dependency service properties must be published along with the service. Any additional service properties specified directly are merged with these.</li> +</ul> +<p>Usage Example: Here, the MyComponent component is injected with a dependency over a "MyDependency" service.</p> +<div class="codehilite"><pre><span class="nd">@Component</span> +<span class="kd">class</span> <span class="nc">MyComponent</span> <span class="o">{</span> + <span class="nd">@ServiceDependency</span><span class="o">(</span><span class="n">timeout</span><span class="o">=</span><span class="mi">15000</span><span class="o">)</span> + <span class="n">MyDependency</span> <span class="n">dependency</span><span class="o">;</span> + <span class="c1">// ...</span> +<span class="o">}</span> +</pre></div> + + +<p>Usage example of a Service whose dependency filter is configured from ConfigAdmin, using a "named" dependency +(please check <a href="">Here</a> for more informations about "named" dependencies):</p> +<div class="codehilite"><pre><span class="cm">/**</span> +<span class="cm"> * A Service whose service dependency "otherService" 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">"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="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 "otherService" 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">"otherService"</span><span class="o">)</span> + <span class="kt">void</span> <span class="nf">bindOtherService</span><span class="o">(</span><span class="n">OtherService</span> <span class="n">other</span><span class="o">)</span> <span class="o">{</span> + <span class="o">}</span> + + <span class="cm">/**</span> +<span class="cm"> * All dependencies are injected and our service is now ready to be published.</span> +<span class="cm"> * Notice that you can also use the publisher service attribute if you need</span> +<span class="cm"> * to take control on service exposition.</span> +<span class="cm"> */</span> + <span class="nd">@Start</span> + <span class="kt">void</span> <span class="nf">start</span><span class="o">()</span> <span class="o">{</span> + <span class="o">}</span> + <span class="o">}</span> +</pre></div> + <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;"> + Rev. 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/diagrams/concurrent-serial-queue.png ============================================================================== Binary file - no diff available. Propchange: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/diagrams/concurrent-serial-queue.png ------------------------------------------------------------------------------ svn:mime-type = image/png Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/diagrams/serial-queue.png ============================================================================== Binary file - no diff available. Propchange: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/diagrams/serial-queue.png ------------------------------------------------------------------------------ svn:mime-type = image/png Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/diagrams/statediagram.png ============================================================================== Binary file - no diff available. Propchange: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/diagrams/statediagram.png ------------------------------------------------------------------------------ svn:mime-type = image/png Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/diagrams/statediagram.uxf ============================================================================== Binary file - no diff available. Propchange: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/diagrams/statediagram.uxf ------------------------------------------------------------------------------ svn:mime-type = application/xml Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/external-links.html ============================================================================== --- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/external-links.html (added) +++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/external-links.html Tue Mar 10 21:03:25 2015 @@ -0,0 +1,87 @@ +<!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 - External Links</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 - External Links</h1> + <p>This page regroups Dependency Manager external articles and related links:</p> +<ul> +<li><a href="https://bitbucket.org/marrs/bndtools-dmdemo";>BndTools based demo of Dependency Manager annotations</a></li> +<li><a href="http://arnhem.luminis.eu/introduction-apache-felix-dependency-manager";>Introduction to Dependency Manager</a></li> +<li><a href="http://arnhem.luminis.eu/introduction-apache-felix-dependencymanager-part-2";>Introduction to Dependency Manager, part II</a></li> +</ul> + <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;"> + Rev. 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>
