Gitiles
Code Review Sign In
gerrit.onosproject.org / onos-felix / 1382a091d3827b780c3dab51ffba231ca9b8348f / . / ipojo / core / doc / configuration-handler.html
blob: 1e8d913c8c2b1a07dd4aa9edace01c181e170639 [file] [log] [blame]
Clement Escoffier6b928e92008-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 Escoffier83507512008-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]6<HEAD>
7 <TITLE>Apache Felix - Configuration Handler</TITLE>
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]8 <LINK rel="stylesheet" href="media.data/site.css" type="text/css" media="all">
Clement Escoffier6b928e92008-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 Escoffier83507512008-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]13 <DIV class="menu">
Clement Escoffier83507512008-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 Escoffier6b928e92008-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 Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]34 </DIV>
Clement Escoffier6b928e92008-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 Escoffier83507512008-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 Escoffier6b928e92008-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 Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]66<SPAN class="code-tag">&lt;/instance&gt;</SPAN>
Clement Escoffier6b928e92008-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 Escoffier83507512008-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 Escoffier6b928e92008-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 Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]98<SPAN class="code-tag">&lt;/instance&gt;</SPAN>
Clement Escoffier6b928e92008-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]110<H6><A name="ConfigurationHandler-Overview"></A><B>Overview</B></H6>
111<UL>
Clement Escoffier83507512008-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 Escoffier6b928e92008-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 Escoffier83507512008-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 Escoffier6b928e92008-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 Escoffier83507512008-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 Escoffier6b928e92008-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 Escoffier83507512008-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 Escoffier6b928e92008-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 Escoffier83507512008-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 Escoffier6b928e92008-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 Escoffier83507512008-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]161</UL>
162
163
164<HR>
165<DIV class="" align="center">
Clement Escoffier83507512008-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]167 </DIV>
168 </BODY>
169
Clement Escoffier83507512008-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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]171</HTML>