Gitiles
Code Review Sign In
gerrit.onosproject.org / onos-felix / 1993d108af0f6efdec8a69eb5a6e91c3022c430b / . / ipojo / core / doc / configuration-handler.html
blob: 8c570655935ccb4dad4494313b18aa206b364e35 [file] [log] [blame]
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]2<html><head>
3
4
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]5
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]6 <title>Apache Felix - Configuration Handler</title>
7 <link rel="stylesheet" href="configuration-handler_files/site.css" type="text/css" media="all">
8 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
9 </head><body>
10 <div class="title"><div class="logo"><a href="http://felix.apache.org/site/index.html"><img alt="Apache Felix" src="configuration-handler_files/logo.png" border="0"></a></div><div class="header"><a href="http://www.apache.org/"><img alt="Apache" src="configuration-handler_files/apache.png" border="0"></a></div></div>
11 <div class="menu">
12<ul>
13 <li><a href="http://felix.apache.org/site/news.html" title="news">news</a></li>
14 <li><a href="http://felix.apache.org/site/license.html" title="license">license</a></li>
15 <li><span class="nobr"><a href="http://felix.apache.org/site/downloads.cgi" title="Visit page outside Confluence" rel="nofollow">downloads<sup><img class="rendericon" src="configuration-handler_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
16 <li><a href="http://felix.apache.org/site/documentation.html" title="documentation">documentation</a></li>
17 <li><a href="http://felix.apache.org/site/mailinglists.html" title="mailinglists">mailing lists</a></li>
18 <li><a href="http://felix.apache.org/site/contributing.html" title="Contributing">contributing</a></li>
19 <li><span class="nobr"><a href="http://www.apache.org/" title="Visit page outside Confluence" rel="nofollow">asf<sup><img class="rendericon" src="configuration-handler_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
20 <li><span class="nobr"><a href="http://www.apache.org/foundation/sponsorship.html" title="Visit page outside Confluence" rel="nofollow">sponsorship<sup><img class="rendericon" src="configuration-handler_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
21 <li><span class="nobr"><a href="http://www.apache.org/foundation/thanks.html" title="Visit page outside Confluence" rel="nofollow">sponsors<sup><img class="rendericon" src="configuration-handler_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]22<!-- ApacheCon Ad -->
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]23<iframe src="configuration-handler_files/button.html" style="border-width: 0pt; float: left;" scrolling="no" width="135" frameborder="0" height="135"></iframe>
24<p style="height: 100px;">
25<!-- ApacheCon Ad -->
26</p></li></ul> </div>
27 <div class="main">
28<table class="sectionMacro" border="0" cellpadding="5" cellspacing="0" width="100%"><tbody><tr>
29<td class="confluenceTd" valign="top" width="80%">
30<h1><a name="ConfigurationHandler-ConfigurationHandler"></a>Configuration Handler</h1>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]31
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]32<p>The configuration handler aims to manage component configuration.
33This handler allows the configuration and dynamic reconfiguration of
34instances. A configuration is a set of couple (name, value). The name
35can be a field name or a property name associated to a field or/and a
36method.</p>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]37
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]38<h2><a name="ConfigurationHandler-ConfigurablePropertyconfiguration"></a>Configurable Property configuration</h2>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]39
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]40<p>To support configuration, the component type needs to declare which
41properties are configurable. These properties are not necessarily
42service property but can be internal component property.</p>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]43
44
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]45<h2><a name="ConfigurationHandler-Examples"></a>Examples</h2>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]46
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]47<div class="code"><div class="codeContent">
48<pre class="code-xml"><span class="code-tag">&lt;iPOJO&gt;</span>
49<span class="code-tag">&lt;Component className=<span class="code-quote">"fr.imag.adele.escoffier.hello.impl.HelloServiceImpl"</span>&gt;</span>
50 <span class="code-tag">&lt;Provides&gt;</span>
51 <span class="code-tag">&lt;Property name=<span class="code-quote">"foo"</span> field=<span class="code-quote">"m_foo"</span>/&gt;</span>
52 <span class="code-tag">&lt;/Provides&gt;</span>
53 <span class="code-tag">&lt;Properties propagation=<span class="code-quote">"false"</span>/&gt;</span>
54 <span class="code-tag">&lt;Property name=<span class="code-quote">"foo"</span> field=<span class="code-quote">"m_foo"</span>/&gt;</span>
55 <span class="code-tag">&lt;Property name=<span class="code-quote">"array"</span> method=<span class="code-quote">"updateArray"</span>/&gt;</span>
56 <span class="code-tag">&lt;Property name=<span class="code-quote">"hello.language"</span> type=<span class="code-quote">"java.lang.String"</span>/&gt;</span>
57 <span class="code-tag">&lt;/Properties&gt;</span>
58<span class="code-tag">&lt;/Component&gt;</span>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]59
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]60<span class="code-tag">&lt;instance component=<span class="code-quote">"fr.imag.adele.escoffier.hello.impl.HelloServiceImpl"</span> name=<span class="code-quote">"HelloService"</span>&gt;</span>
61 <span class="code-tag">&lt;property name=<span class="code-quote">"foo"</span> value=<span class="code-quote">"bar"</span>/&gt;</span>
62 <span class="code-tag">&lt;property name=<span class="code-quote">"array"</span> value=<span class="code-quote">"\{1, 2, 3}"</span>/&gt;</span>
63 <span class="code-tag">&lt;property name=<span class="code-quote">"hello.language"</span> value=<span class="code-quote">"en"</span>/&gt;</span>
64<span class="code-tag">&lt;/instance&gt;</span>
65<span class="code-tag">&lt;/iPOJO&gt;</span></pre>
66</div></div>
67<p>In the previous snippet, you can see three configurable properties.
68The first is a configurable property attached to the field 'foo' that
69is a service property too. The second is an array property attached to
70a method (updatArray). The third property is a <em>static</em> property, in the sense that neither field nor method is attached to this property.</p>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]71
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]72<p>These three properties are configured by the instance configuration.</p>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]73
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]74<p>By setting the attribute <b>propagation</b> to <b>"true"</b>, you
75allow the property propagation to the service registration. It means
76that at each time that the configuration of the instance is updated;
77all properties contained in the configuration are propagated to the
78service registrations. For example, in the previous example, not only <em>foo</em> will be published but <em>array</em> and <em>hello.language</em> are also published.<br>
79If a property has a method, this method is invoked each time that the
80property value changes (the method is called to push the initial value
81just after the constructor). The method receives one argument of the
82type of the property (an integer array in the example).</p>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]83
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]84<h2><a name="ConfigurationHandler-ExposingaManagedService"></a>Exposing a Managed Service</h2>
85<p>The ManagedService is a service specified in the OSGi Compendium. It
86allows reconfiguring an instance with the Configuration Admin. There is
87two way for an iPOJO instance to expose a Managed Service.<br>
88• In the component type description by adding the <em>pid</em> attribute in the properties element <br>
89• In the instance configuration by configuring the <em>managed.service.pid</em> property</p>
90<div class="code"><div class="codeContent">
91<pre class="code-xml"><span class="code-tag">&lt;iPOJO&gt;</span>
92<span class="code-tag">&lt;Component className=<span class="code-quote">"fr.imag.adele.escoffier.hello.impl.HelloServiceImpl"</span>&gt;</span>
93 <span class="code-tag">&lt;Provides&gt;</span>
94 <span class="code-tag">&lt;Property name=<span class="code-quote">"foo"</span> field=<span class="code-quote">"m_foo"</span>/&gt;</span>
95 <span class="code-tag">&lt;/Provides&gt;</span>
96 <span class="code-tag">&lt;Properties propagation=<span class="code-quote">"false"</span> pid=<span class="code-quote">"mymanagedservicepid"</span>/&gt;</span>
97 <span class="code-tag">&lt;Property name=<span class="code-quote">"foo"</span> field=<span class="code-quote">"m_foo"</span>/&gt;</span>
98 <span class="code-tag">&lt;Property name=<span class="code-quote">"array"</span> method=<span class="code-quote">"updateArray"</span>/&gt;</span>
99 <span class="code-tag">&lt;Property name=<span class="code-quote">"hello.language"</span> type=<span class="code-quote">"java.lang.String"</span>/&gt;</span>
100 <span class="code-tag">&lt;/Properties&gt;</span>
101<span class="code-tag">&lt;/Component&gt;</span>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]102
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]103<span class="code-tag">&lt;instance component=<span class="code-quote">"fr.imag.adele.escoffier.hello.impl.HelloServiceImpl"</span> name=<span class="code-quote">"HelloService"</span>&gt;</span>
104 <span class="code-tag">&lt;property name=<span class="code-quote">"foo"</span> value=<span class="code-quote">"bar"</span>/&gt;</span>
105 <span class="code-tag">&lt;property name=<span class="code-quote">"array"</span> value=<span class="code-quote">"\{1, 2, 3}"</span>/&gt;</span>
106 <span class="code-tag">&lt;property name=<span class="code-quote">"hello.language"</span> value=<span class="code-quote">"en"</span>/&gt;</span>
107 <span class="code-tag">&lt;property name=<span class="code-quote">"managed.service.pid"</span> value=<span class="code-quote">"mymanagedservicepid2"</span>/&gt;</span>
108<span class="code-tag">&lt;/instance&gt;</span>
109<span class="code-tag">&lt;/iPOJO&gt;</span></pre>
110</div></div>
111<p><em>Note</em>: if specified in the two locations, the instance configuration is used.</p>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]112
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]113<p>The managed service pid is the identifier used by the Configuration
114Admin to attach configuration to Managed Services. First this pid must
115be unique (as any pid in OSGi). Moreover, this pid cannot be the same
116one that the pid used in the Managed Service Factory to create the
117instance (if you use this way to create your instance).</p>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]118
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]119<p>When an instance is reconfigured with the Managed Service, the configuration is propagated if the propagation is enabled.</p>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]120
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]121<h2><a name="ConfigurationHandler-DynamicReconfigurationusingFactoriesorManagedServiceFactories"></a>Dynamic Reconfiguration using Factories or ManagedServiceFactories</h2>
122<p>The handler supports reconfiguration. To reconfigure an instance you
123can use both iPOJO Factory and the ManagedServiceFactory exposed by the
124factory of the targeted instance. By calling the method <em>reconfigure</em> or <em>update</em>
125(according of the service do you use), the handler receive the new
126configuration and apply it. If the propagation is activated, the
127service registrations are updated too.</p></td>
128<td class="confluenceTd" valign="top" width="20%">
129<h6><a name="ConfigurationHandler-Overview"></a><b>Overview</b></h6>
130<ul>
131 <li><a href="http://felix.apache.org/site/apache-felix-ipojo.html" title="Apache Felix iPOJO">Home Page</a></li>
132 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-feature-overview.html" title="Apache Felix iPOJO Feature Overview">iPOJO Feature Overview</a></li>
133 <li><a href="http://felix.apache.org/site/download.html" title="Download">Download &amp; Install </a></li>
134</ul>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]135
136
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]137<h6><a name="ConfigurationHandler-GettingStarted"></a><b>Getting Started</b></h6>
138<ul>
139 <li><a href="http://felix.apache.org/site/ipojo-in-10-minutes.html" title="iPOJO in 10 minutes">iPOJO in 10 minutes</a></li>
140 <li><a href="http://felix.apache.org/site/how-to-use-ipojo-annotations.html" title="How to use iPOJO Annotations">How to use iPOJO Annotations</a></li>
141 <li><a href="http://felix.apache.org/site/ipojo-hello-word-maven-based-tutorial.html" title="iPOJO Hello Word (Maven-Based) tutorial">iPOJO Hello Word (Maven-Based) tutorial</a></li>
142 <li><a href="http://felix.apache.org/site/ipojo-advanced-tutorial.html" title="iPOJO Advanced Tutorial">iPOJO Advanced Tutorial</a></li>
143 <li><a href="http://felix.apache.org/site/ipojo-composition-tutorial.html" title="iPOJO Composition Tutorial">iPOJO Composition Tutorial</a></li>
144</ul>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]145
146
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]147<h6><a name="ConfigurationHandler-UserGuide"></a><b>User Guide</b></h6>
148<ul>
149 <li><a href="http://felix.apache.org/site/describing-components.html" title="Describing components">Describing components (handler list) </a></li>
150 <li><a href="http://felix.apache.org/site/using-xml-schemas.html" title="Using XML Schemas">Using XML Schemas</a></li>
151 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-testing-components.html" title="apache-felix-ipojo-testing-components">Testing components</a></li>
152 <li><a href="http://felix.apache.org/site/ipojo-advanced-topics.html" title="iPOJO Advanced Topics">Advanced Topics</a></li>
153 <li><a href="http://felix.apache.org/site/ipojo-faq.html" title="iPOJO FAQ">FAQ</a></li>
154</ul>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]155
156
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]157<h6><a name="ConfigurationHandler-Tools"></a><b>Tools</b></h6>
158<ul>
159 <li><a href="http://felix.apache.org/site/ipojo-eclipse-plug-in.html" title="iPOJO Eclipse Plug-in">iPOJO Eclipse Plug-in</a></li>
160 <li><a href="http://felix.apache.org/site/ipojo-ant-task.html" title="iPOJO Ant Task">iPOJO Ant Task</a></li>
161 <li><a href="http://felix.apache.org/site/ipojo-maven-plug-in.html" title="iPOJO Maven Plug-in">iPOJO Maven Plug-in</a></li>
162 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-junit4osgi.html" title="apache-felix-ipojo-junit4osgi">Junit4OSGi</a></li>
163 <li><a href="http://felix.apache.org/site/ipojo-concepts-overview.html" title="iPOJO Concepts Overview">iPOJO concepts overview</a></li>
164</ul>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]165
166
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]167<h6><a name="ConfigurationHandler-DeveloperGuide"></a><b>Developer Guide</b></h6>
168<ul>
169 <li>API: <span class="nobr"><a href="http://people.apache.org/%7Eclement/ipojo/api/1.0/" title="Visit page outside Confluence" rel="nofollow">1.0<sup><img class="rendericon" src="configuration-handler_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
170 <li><a href="http://felix.apache.org/site/how-to-write-your-own-handler.html" title="How to write your own handler">How to write your own handler</a></li>
171 <li><a href="http://felix.apache.org/site/how-to-use-ipojo-manipulation-metadata.html" title="How to use iPOJO Manipulation Metadata">How to use iPOJO Manipulation Metadata</a></li>
172 <li><a href="http://felix.apache.org/site/dive-into-the-ipojo-manipulation-depths.html" title="Dive into the iPOJO Manipulation depths">Dive into the iPOJO Manipulation depths</a></li>
173</ul>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]174
175
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]176<h6><a name="ConfigurationHandler-Misc&amp;Contact"></a><b>Misc &amp; Contact</b></h6>
177<ul>
178 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-issuestracker.html" title="apache-felix-ipojo-issuestracker">Issues Tracker</a></li>
179 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-supportedvms.html" title="apache-felix-ipojo-supportedVMs">Supported JVMs</a></li>
180 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-supportedosgi.html" title="apache-felix-ipojo-supportedOSGi">Supported OSGi Implementations</a></li>
181 <li><span class="nobr"><a href="http://ipojo-dark-side.blogspot.com/" title="Visit page outside Confluence" rel="nofollow">iPOJO's Dark Side Blog<sup><img class="rendericon" src="configuration-handler_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
182 <li><a href="http://felix.apache.org/site/future-ideas.html" title="Future Ideas">Future Ideas</a></li>
183 <li><a href="http://felix.apache.org/site/contact.html" title="Contact">Contact</a></li>
184 <li><a href="http://felix.apache.org/site/related-works.html" title="Related Works">Related Works</a></li>
185 <li><a href="http://felix.apache.org/site/article-presentations.html" title="Article &amp; Presentations">Article &amp; Presentations</a></li>
186</ul>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]187
188
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]189<hr>
190<div class="" align="center">
191<p><span class="nobr"><a href="http://cwiki.apache.org/confluence/createrssfeed.action?types=blogpost&amp;statuses=created&amp;statuses=modified&amp;spaces=FELIX&amp;labelString=iPOJO&amp;rssType=atom&amp;maxResults=10&amp;timeSpan=5&amp;publicFeed=true&amp;title=iPOJO%20Atom%20Feed" title="Stay tuned!" rel="nofollow"><img src="configuration-handler_files/feed-icon-32x32.png" align="absmiddle" border="0"><sup><img class="rendericon" src="configuration-handler_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></p></div>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]192
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame]193<script type="text/javascript">
194var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
195document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
196</script><script src="configuration-handler_files/ga.js" type="text/javascript"></script>
197<script type="text/javascript">
198var pageTracker = _gat._getTracker("UA-1518442-4");
199pageTracker._trackPageview();
200</script>
201</td></tr></tbody></table>
202 </div>
203 </body></html>