Gitiles
Code Review Sign In
gerrit.onosproject.org / onos-felix / a095881fc41f18d7e673ca36ff2b03716ced166a / . / ipojo / core / doc / configuration-handler.html
blob: 1e8d913c8c2b1a07dd4aa9edace01c181e170639 [file] [log] [blame]
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]1
2<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3<HTML>
4
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]5<!-- Mirrored Site: felix.apache.org. File: /site/configuration-handler.html. Date: Mon, 13 Oct 2008 06:53:07 GMT -->
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]6<HEAD>
7 <TITLE>Apache Felix - Configuration Handler</TITLE>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]8 <LINK rel="stylesheet" href="media.data/site.css" type="text/css" media="all">
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]9 <META http-equiv="Content-Type" content="text/html;charset=UTF-8">
10 </HEAD>
11 <BODY>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]12 <DIV class="title"><DIV class="logo"><A href="index.html"><IMG border="0" alt="Apache Felix" src="media.data/logo.png"></A></DIV><DIV class="header"><A href="http://www.apache.org/"><IMG border="0" alt="Apache" src="media.data/apache.png"></A></DIV></DIV>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]13 <DIV class="menu">
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]14
15
16
17
18
19 <UL>
20 <LI><A href="news.html" title="news">news</A></LI>
21 <LI><A href="license.html" title="license">license</A></LI>
22 <LI><SPAN class="nobr"><A href="downloads.html" title="Visit page outside Confluence" rel="nofollow">downloads<SUP><IMG class="rendericon" src="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>
23 <LI><A href="documentation.html" title="documentation">documentation</A></LI>
24 <LI><A href="mailinglists.html" title="mailinglists">mailing lists</A></LI>
25 <LI><A href="contributing.html" title="Contributing">contributing</A></LI>
26 <LI><SPAN class="nobr"><A href="http://www.apache.org/" title="Visit page outside Confluence" rel="nofollow">asf<SUP><IMG class="rendericon" src="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>
27 <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="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>
28 <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="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]29<!-- ApacheCon Ad -->
30<IFRAME src="http://www.apache.org/ads/button.html" style="border-width:0; float: left" frameborder="0" scrolling="no" width="135" height="135"></IFRAME>
31<P style="height: 100px">
32<!-- ApacheCon Ad --></LI>
33</UL>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]34 </DIV>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]35 <DIV class="main">
36<TABLE class="sectionMacro" border="0" cellpadding="5" cellspacing="0" width="100%"><TBODY><TR>
37<TD class="confluenceTd" valign="top" width="80%">
38<H1><A name="ConfigurationHandler-ConfigurationHandler"></A>Configuration Handler</H1>
39
40<P>The configuration handler aims to manage component configuration. This handler allows the configuration and dynamic reconfiguration of instances. A configuration is a set of couple (name, value). The name can be a field name or a property name associated to a field or/and a method.</P>
41
42<H2><A name="ConfigurationHandler-ConfigurablePropertyconfiguration"></A>Configurable Property configuration</H2>
43
44<P>To support configuration, the component type needs to declare which properties are configurable. These properties are not necessarily service property but can be internal component property.</P>
45
46
47<H2><A name="ConfigurationHandler-Examples"></A>Examples</H2>
48
49<DIV class="code"><DIV class="codeContent">
50<PRE class="code-xml"><SPAN class="code-tag">&lt;iPOJO&gt;</SPAN>
51<SPAN class="code-tag">&lt;Component className=<SPAN class="code-quote">&quot;fr.imag.adele.escoffier.hello.impl.HelloServiceImpl&quot;</SPAN>&gt;</SPAN>
52 <SPAN class="code-tag">&lt;Provides&gt;</SPAN>
53 <SPAN class="code-tag">&lt;Property name=<SPAN class="code-quote">&quot;foo&quot;</SPAN> field=<SPAN class="code-quote">&quot;m_foo&quot;</SPAN>/&gt;</SPAN>
54 <SPAN class="code-tag">&lt;/Provides&gt;</SPAN>
55 <SPAN class="code-tag">&lt;Properties propagation=<SPAN class="code-quote">&quot;false&quot;</SPAN>/&gt;</SPAN>
56 <SPAN class="code-tag">&lt;Property name=<SPAN class="code-quote">&quot;foo&quot;</SPAN> field=<SPAN class="code-quote">&quot;m_foo&quot;</SPAN>/&gt;</SPAN>
57 <SPAN class="code-tag">&lt;Property name=<SPAN class="code-quote">&quot;array&quot;</SPAN> method=<SPAN class="code-quote">&quot;updateArray&quot;</SPAN>/&gt;</SPAN>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]58 <SPAN class="code-tag">&lt;Property name=<SPAN class="code-quote">&quot;hello.language&quot;</SPAN> type=<SPAN class="code-quote">&quot;java.lang.String&quot;</SPAN>/&gt;</SPAN>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]59 <SPAN class="code-tag">&lt;/Properties&gt;</SPAN>
60<SPAN class="code-tag">&lt;/Component&gt;</SPAN>
61
62<SPAN class="code-tag">&lt;instance component=<SPAN class="code-quote">&quot;fr.imag.adele.escoffier.hello.impl.HelloServiceImpl&quot;</SPAN> name=<SPAN class="code-quote">&quot;HelloService&quot;</SPAN>&gt;</SPAN>
63 <SPAN class="code-tag">&lt;property name=<SPAN class="code-quote">&quot;foo&quot;</SPAN> value=<SPAN class="code-quote">&quot;bar&quot;</SPAN>/&gt;</SPAN>
64 <SPAN class="code-tag">&lt;property name=<SPAN class="code-quote">&quot;array&quot;</SPAN> value=<SPAN class="code-quote">&quot;\{1, 2, 3}&quot;</SPAN>/&gt;</SPAN>
65 <SPAN class="code-tag">&lt;property name=<SPAN class="code-quote">&quot;hello.language&quot;</SPAN> value=<SPAN class="code-quote">&quot;en&quot;</SPAN>/&gt;</SPAN>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]66<SPAN class="code-tag">&lt;/instance&gt;</SPAN>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]67<SPAN class="code-tag">&lt;/iPOJO&gt;</SPAN></PRE>
68</DIV></DIV>
69<P>In the previous snippet, you can see three configurable properties. The first is a configurable property attached to the field 'foo' that is a service property too. The second is an array property attached to a 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>
70
71<P>These three properties are configured by the instance configuration.</P>
72
73<P>By setting the attribute <B>propagation</B> to <B>&quot;true&quot;</B>, you allow the property propagation to the service registration. It means that at each time that the configuration of the instance is updated; all properties contained in the configuration are propagated to the service 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>
74If a property has a method, this method is invoked each time that the property value changes (the method is called to push the initial value just after the constructor). The method receives one argument of the type of the property (an integer array in the example).</P>
75
76<H2><A name="ConfigurationHandler-ExposingaManagedService"></A>Exposing a Managed Service</H2>
77<P>The ManagedService is a service specified in the OSGi Compendium. It allows reconfiguring an instance with the Configuration Admin. There is two way for an iPOJO instance to expose a Managed Service.<BR>
78&bull; In the component type description by adding the <EM>pid</EM> attribute in the properties element <BR>
79&bull; In the instance configuration by configuring the <EM>managed.service.pid</EM> property</P>
80<DIV class="code"><DIV class="codeContent">
81<PRE class="code-xml"><SPAN class="code-tag">&lt;iPOJO&gt;</SPAN>
82<SPAN class="code-tag">&lt;Component className=<SPAN class="code-quote">&quot;fr.imag.adele.escoffier.hello.impl.HelloServiceImpl&quot;</SPAN>&gt;</SPAN>
83 <SPAN class="code-tag">&lt;Provides&gt;</SPAN>
84 <SPAN class="code-tag">&lt;Property name=<SPAN class="code-quote">&quot;foo&quot;</SPAN> field=<SPAN class="code-quote">&quot;m_foo&quot;</SPAN>/&gt;</SPAN>
85 <SPAN class="code-tag">&lt;/Provides&gt;</SPAN>
86 <SPAN class="code-tag">&lt;Properties propagation=<SPAN class="code-quote">&quot;false&quot;</SPAN> pid=<SPAN class="code-quote">&quot;mymanagedservicepid&quot;</SPAN>/&gt;</SPAN>
87 <SPAN class="code-tag">&lt;Property name=<SPAN class="code-quote">&quot;foo&quot;</SPAN> field=<SPAN class="code-quote">&quot;m_foo&quot;</SPAN>/&gt;</SPAN>
88 <SPAN class="code-tag">&lt;Property name=<SPAN class="code-quote">&quot;array&quot;</SPAN> method=<SPAN class="code-quote">&quot;updateArray&quot;</SPAN>/&gt;</SPAN>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]89 <SPAN class="code-tag">&lt;Property name=<SPAN class="code-quote">&quot;hello.language&quot;</SPAN> type=<SPAN class="code-quote">&quot;java.lang.String&quot;</SPAN>/&gt;</SPAN>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]90 <SPAN class="code-tag">&lt;/Properties&gt;</SPAN>
91<SPAN class="code-tag">&lt;/Component&gt;</SPAN>
92
93<SPAN class="code-tag">&lt;instance component=<SPAN class="code-quote">&quot;fr.imag.adele.escoffier.hello.impl.HelloServiceImpl&quot;</SPAN> name=<SPAN class="code-quote">&quot;HelloService&quot;</SPAN>&gt;</SPAN>
94 <SPAN class="code-tag">&lt;property name=<SPAN class="code-quote">&quot;foo&quot;</SPAN> value=<SPAN class="code-quote">&quot;bar&quot;</SPAN>/&gt;</SPAN>
95 <SPAN class="code-tag">&lt;property name=<SPAN class="code-quote">&quot;array&quot;</SPAN> value=<SPAN class="code-quote">&quot;\{1, 2, 3}&quot;</SPAN>/&gt;</SPAN>
96 <SPAN class="code-tag">&lt;property name=<SPAN class="code-quote">&quot;hello.language&quot;</SPAN> value=<SPAN class="code-quote">&quot;en&quot;</SPAN>/&gt;</SPAN>
97 <SPAN class="code-tag">&lt;property name=<SPAN class="code-quote">&quot;managed.service.pid&quot;</SPAN> value=<SPAN class="code-quote">&quot;mymanagedservicepid2&quot;</SPAN>/&gt;</SPAN>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]98<SPAN class="code-tag">&lt;/instance&gt;</SPAN>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]99<SPAN class="code-tag">&lt;/iPOJO&gt;</SPAN></PRE>
100</DIV></DIV>
101<P><EM>Note</EM>: if specified in the two locations, the instance configuration is used.</P>
102
103<P>The managed service pid is the identifier used by the Configuration Admin to attach configuration to Managed Services. First this pid must be unique (as any pid in OSGi). Moreover, this pid cannot be the same one that the pid used in the Managed Service Factory to create the instance (if you use this way to create your instance).</P>
104
105<P>When an instance is reconfigured with the Managed Service, the configuration is propagated if the propagation is enabled.</P>
106
107<H2><A name="ConfigurationHandler-DynamicReconfigurationusingFactoriesorManagedServiceFactories"></A>Dynamic Reconfiguration using Factories or ManagedServiceFactories</H2>
108<P>The handler supports reconfiguration. To reconfigure an instance you can use both iPOJO Factory and the ManagedServiceFactory exposed by the factory of the targeted instance. By calling the method <EM>reconfigure</EM> or <EM>update</EM> (according of the service do you use), the handler receive the new configuration and apply it. If the propagation is activated, the service registrations are updated too.</P></TD>
109<TD class="confluenceTd" valign="top" width="20%">
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]110<H6><A name="ConfigurationHandler-Overview"></A><B>Overview</B></H6>
111<UL>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]112 <LI><A href="apache-felix-ipojo.html" title="Apache Felix iPOJO">Home Page</A></LI>
113 <LI><A href="apache-felix-ipojo-feature-overview.html" title="Apache Felix iPOJO Feature Overview">iPOJO Feature Overview</A></LI>
114 <LI><A href="download.html" title="Download">Download &amp; Install </A></LI>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]115</UL>
116
117
118<H6><A name="ConfigurationHandler-GettingStarted"></A><B>Getting Started</B></H6>
119<UL>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]120 <LI><A href="ipojo-in-10-minutes.html" title="iPOJO in 10 minutes">iPOJO in 10 minutes</A></LI>
121 <LI><A href="ipojo-hello-word-maven-based-tutorial.html" title="iPOJO Hello Word (Maven-Based) tutorial">iPOJO Hello Word &#40;Maven&#45;Based&#41; tutorial</A></LI>
122 <LI><A href="ipojo-advanced-tutorial.html" title="iPOJO Advanced Tutorial">iPOJO Advanced Tutorial</A></LI>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]123</UL>
124
125
126<H6><A name="ConfigurationHandler-UserGuide"></A><B>User Guide</B></H6>
127<UL>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]128 <LI><A href="describing-components.html" title="Describing components">Describing components (handler list) </A></LI>
129 <LI><A href="how-to-use-ipojo-annotations.html" title="How to use iPOJO Annotations">How to use iPOJO Annotations</A></LI>
130 <LI><A href="ipojo-advanced-topics.html" title="iPOJO Advanced Topics">Advanced Topics</A></LI>
131 <LI><A href="ipojo-faq.html" title="iPOJO FAQ">FAQ</A></LI>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]132</UL>
133
134
135<H6><A name="ConfigurationHandler-Tools"></A><B>Tools</B></H6>
136<UL>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]137 <LI><A href="ipojo-eclipse-plug-in.html" title="iPOJO Eclipse Plug-in">iPOJO Eclipse Plug&#45;in</A></LI>
138 <LI><A href="ipojo-ant-task.html" title="iPOJO Ant Task">iPOJO Ant Task</A></LI>
139 <LI><A href="ipojo-maven-plug-in.html" title="iPOJO Maven Plug-in">iPOJO Maven Plug&#45;in</A></LI>
140 <LI><A href="ipojo-concepts-overview.html" title="iPOJO Concepts Overview">iPOJO concepts overview</A></LI>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]141</UL>
142
143
144<H6><A name="ConfigurationHandler-DeveloperGuide"></A><B>Developer Guide</B></H6>
145<UL>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]146 <LI>API: <SPAN class="nobr"><A href="http://people.apache.org/~clement/ipojo/api/0.8/" title="Visit page outside Confluence" rel="nofollow">0.8<SUP><IMG class="rendericon" src="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>
147 <LI><A href="how-to-write-your-own-handler.html" title="How to write your own handler">How to write your own handler</A></LI>
148 <LI><A href="how-to-use-ipojo-manipulation-metadata.html" title="How to use iPOJO Manipulation Metadata">How to use iPOJO Manipulation Metadata</A></LI>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]149</UL>
150
151
152<H6><A name="ConfigurationHandler-Misc%26Contact"></A><B>Misc &amp; Contact</B></H6>
153<UL>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]154 <LI><A href="apache-felix-ipojo-issuestracker.html" title="apache-felix-ipojo-issuestracker">Issues Tracker</A></LI>
155 <LI><A href="apache-felix-ipojo-supportedvms.html" title="apache-felix-ipojo-supportedVMs">Supported JVMs</A></LI>
156 <LI><A href="apache-felix-ipojo-supportedosgi.html" title="apache-felix-ipojo-supportedOSGi">Supported OSGi Implementations</A></LI>
157 <LI><A href="future-ideas.html" title="Future Ideas">Future Ideas</A></LI>
158 <LI><A href="contact.html" title="Contact">Contact</A></LI>
159 <LI><A href="related-works.html" title="Related Works">Related Works</A></LI>
160 <LI><A href="article-presentations.html" title="Article & Presentations">Article &amp; Presentations</A></LI>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]161</UL>
162
163
164<HR>
165<DIV class="" align="center">
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]166<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="../../cwiki.apache.org/confluence/images/icons/feed-icon-32x32.png" align="absmiddle" border="0"><SUP><IMG class="rendericon" src="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></P></DIV></TD></TR></TBODY></TABLE>
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]167 </DIV>
168 </BODY>
169
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]170<!-- Mirrored Site: felix.apache.org. File: /site/configuration-handler.html. Date: Mon, 13 Oct 2008 06:53:07 GMT -->
Clement Escoffier50254022008-05-16 20:33:54 +0000[diff] [blame]171</HTML>