Gitiles
Code Review Sign In
gerrit.onosproject.org / onos-felix / 3e171b59e949cf93d8be5c0654ec7a8ee138d55a / . / ipojo / core / doc / configuration-handler.html
blob: 8c570655935ccb4dad4494313b18aa206b364e35 [file] [log] [blame]
Clement Escoffier6b928e92008-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 Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]2<html><head>
3
4
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]5
Clement Escoffier8251f602009-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]22<!-- ApacheCon Ad -->
Clement Escoffier8251f602009-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]31
Clement Escoffier8251f602009-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]37
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]38<h2><a name="ConfigurationHandler-ConfigurablePropertyconfiguration"></a>Configurable Property configuration</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]39
Clement Escoffier8251f602009-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]43
44
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]45<h2><a name="ConfigurationHandler-Examples"></a>Examples</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]46
Clement Escoffier8251f602009-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]59
Clement Escoffier8251f602009-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]71
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]72<p>These three properties are configured by the instance configuration.</p>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]73
Clement Escoffier8251f602009-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]83
Clement Escoffier8251f602009-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]102
Clement Escoffier8251f602009-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]112
Clement Escoffier8251f602009-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]118
Clement Escoffier8251f602009-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]120
Clement Escoffier8251f602009-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]135
136
Clement Escoffier8251f602009-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]145
146
Clement Escoffier8251f602009-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]155
156
Clement Escoffier8251f602009-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]165
166
Clement Escoffier8251f602009-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]174
175
Clement Escoffier8251f602009-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]187
188
Clement Escoffier8251f602009-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]192
Clement Escoffier8251f602009-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>