You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@felix.apache.org by bu...@apache.org on 2013/02/03 07:45:22 UTC
svn commit: r849204 [18/33] - in /websites/staging/felix/trunk/content: ./
documentation/subprojects/ documentation/subprojects/apache-felix-ipojo/
documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/
documentation/subprojects/apac...
Modified: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/controller-lifecycle-handler.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/controller-lifecycle-handler.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/controller-lifecycle-handler.html Sun Feb 3 06:45:21 2013
@@ -20,9 +20,45 @@
<head>
<title>Apache Felix - Controller Lifecycle Handler</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">
+ <link rel="stylesheet" href="/site/media.data/site.css" type="text/css" media="all">
+ <link rel="stylesheet" href="/ipojo/site/superfish.css" type="text/css" media="all">
+ <link rel="stylesheet" href="/ipojo/site/style.css" type="text/css" media="all">
<meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+
+ <!--
+ <script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shCore.js"></script>
+ <script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushCSharp.js"></script>
+ <script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushPhp.js"></script>
+ <script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushJScript.js"></script>
+ <script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushVb.js"></script>
+ <script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushSql.js"></script>
+ <script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushXml.js"></script>
+ <script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushShell.js"></script>
+ <script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushDelphi.js"></script>
+ <script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushPython.js"></script>
+ <script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushJava.js"></script>
+ -->
+
+ <script type="text/javascript" src="/ipojo/site/jquery-1.js"></script>
+ <script type="text/javascript" src="/ipojo/site/hoverIntent.js"></script>
+ <script type="text/javascript" src="/ipojo/site/superfish.js"></script>
+ <script type="text/javascript" src="/ipojo/site/supersubs.js"></script>
+
+ <script type="text/javascript">
+
+ $(document).ready(function(){
+ $("ul.sf-menu").supersubs({
+ minWidth: 14, // minimum width of sub-menus in em units
+ maxWidth: 30, // maximum width of sub-menus in em units
+ extraWidth: 1 // extra width can ensure lines don't sometimes turn over
+ // due to slight rounding differences and font-family
+ }).superfish(); // call supersubs first, then superfish, so that subs are
+ // not display:none when measuring. Call before initialising
+ // containing tabs for same reason.
+ });
+
+ </script>
+
</head>
<body>
<div class="title">
@@ -37,96 +73,190 @@
</a>
</div>
</div>
+
+ <div class="main">
+ <div class="main">
+ <div class="page-header">
+ <img src="/ipojo/site/header.png" class="header">
+ <a href="http://ipojo.org"><img src="/ipojo/site/ipojo.png" width="225" class="header-logo"></a>
+ <ul class="sf-menu sf-js-enabled sf-shadow" id="ipojo-menu">
+ <li class="current">
+ <!-- Menu Overview -->
+ <a href="#" class="sf-with-ul">Overview<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
+ <ul>
+ <li>
+ <a href="">Home</a>
+ </li>
+ <li>
+ <a href="">Why choose iPOJO</a>
+ </li>
+ <li>
+ <a href="">Success stories</a>
+ </li>
+ <li>
+ <a href="">Features</a>
+ </li>
+ </ul>
+ </li>
- <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> <br />
-</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>
+ <li class="">
+ <!-- Menu download -->
+ <li>
+ <a href="/downloads.cgi">Download </a>
+ </li>
- <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-ipojo.html">Apache Felix iPOJO</a> » <a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide.html">apache-felix-ipojo-userguide</a> » <a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components.html">Describing components</a>
- </div>
-
+ <li class="">
+ <!-- Menu Documentation -->
+ <a href="#" class="sf-with-ul">Documentation<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
+ <ul>
+ <!-- sub-menu : getting started -->
+ <li class="">
+ <a href="#" class="sf-with-ul">Getting Started<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
+ <ul>
+ <li><a href="">iPOJO in 10 minutes</a></li>
+ <li><a href="">Using Annotations</a></li>
+ <li><a href="">Maven tutorial</a></li>
+ <li><a href="">Advanced tutorial</a></li>
+ <li><a href="">Using Distributed OSGi</a></li>
+ <li><a href="">Application Composition</a></li>
+ </ul>
+ </li> <!-- end of getting started -->
+ <!-- sub menu : Describing Components -->
+ <li class="">
+ <a href="" class="sf-with-ul">Describing components<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
+ <ul>
+ <li><a href="">Requiring a service</a></li>
+ <li><a href="">Providing a service</a></li>
+ <li><a href="">Lifecycle management</a></li>
+ <li><a href="">Configuration</a></li>
+ <li><a href="">Introspection</a></li>
+ <li><a href="">Impacting the lifecycle</a></li>
+ <li><a href="">Asynchronous communication</a></li>
+ <li><a href="">JMX management</a></li>
+ <li><a href="">Extender pattern</a></li>
+ <li><a href="">Whiteboard pattern</a></li>
+ <li><a href="">Temporal dependencies</a></li>
+ </ul>
+ </li> <!-- End of describing components -->
+ <!-- sub-menu : User Guide -->
+ <li class="">
+ <a href="" class="sf-with-ul">User Guide<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
+ <ul>
+ <li><a href="">iPOJO and config admin</a></li>
+ <li><a href="">Factories and Instances</a></li>
+ <li><a href="">XML Schemas</a></li>
+ <li><a href="">API</a></li>
+ <li><a href="">Testing components</a></li>
+ <li><a href="">Eclipse Integration</a></li>
+ <li><a href="">FAQ</a></li>
+ <li><a href="">Reference Card</a></li>
+ </ul>
+ </li> <!-- end of user guide -->
+ <!-- sub-menu : Dev Guide -->
+ <li>
+ <a href="#" class="sf-with-ul">Advanced Topics<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
+ <ul>
+ <li><a href="http://felix.apache.org/ipojo/api/1.6.0">Javadoc</a></li>
+ <li><a href="">Handler development</a></li>
+ <li><a href="">Manipulation Metadata </a></li>
+ <li><a href="">Dive into the iPOJO Manipulation depths</a></li>
+ </ul>
+ </li> <!-- End of Dev guide -->
+ </ul>
+ </li> <!-- End of doc -->
+ <!-- Menu 4 : Tools -->
+ <li class="">
+ <a href="#" class="sf-with-ul">Tools<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
+ <ul>
+ <li><a href="">Ant Task</a></li>
+ <li><a href="">Eclipse Plugin</a></li>
+ <li><a href="">Maven Plugin</a></li>
+ <li><a href="">`arch` shell command</a></li>
+ <li><a href="">Online Manipulator</a></li>
+ <li><a href="">Webconsole plugin</a></li>
+ <li><a href="">Junit4OSGi</a></li>
+ </ul>
+ </li><!-- End of tools -->
+ <!-- Menu 5 : Support -->
+ <li>
+ <a href="">Support </a>
+ </li>
+ <!-- End of the menu 5 -->
+ <!-- Menu 6 : Misc -->
+ <li class="">
+ <a href="#" class="sf-with-ul">Misc<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
+ <ul>
+ <li><a href="">Supported JVMs</a></li>
+ <li><a href="">Supported OSGi Implementations</a></li>
+ <li><a href="http://ipojo-dark-side.blogspot.com">iPOJO's Dark Side Blog</a></li>
+ <li><a href="">Article & Presentations</a></li>
+ <li><a href="http://www.apache.org/">ASF</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
+ <li><a href="http://www.apache.org/foundation/thanks.html">Sponsors</a></li>
+ </ul>
+ </li><!-- End of misc -->
+ </ul> <!-- End of the menu -->
+ </div> <!-- Page header -->
+
+ <!--
<div class="tip">
This page is a translated version of <a href="/site/controller-lifecycle-handler.html" target="felix_cwiki">/site/controller-lifecycle-handler.html</a>. In case of
doubt you might want to refer to the old page.
</div>
+ -->
<h1>Controller Lifecycle Handler</h1>
- <p>{include:apache-felix-ipojo-header}</p>
-<div class="content">
-
-# Lifecycle Controller Handler
-
-*The lifecycle controller allows a component implementation to participate to the instance lifecycle. So, you can immediately decide to stop an instance if the configuration is incorrect (correct properties, accessible resources...). The licecyel controller impacts the instance lifecycle, if you want to impact only the registered service, have a look to the service controller ([service providing]()).*
-
-{div:class=toc}
+
+ <div class="content">
+ <h1 id="lifecycle-controller-handler">Lifecycle Controller Handler</h1>
+<p><em>The lifecycle controller allows a component implementation to participate to the instance lifecycle. So, you can immediately decide to stop an instance if the configuration is incorrect (correct properties, accessible resources...). The licecyel controller impacts the instance lifecycle, if you want to impact only the registered service, have a look to the service controller (<a href="">service providing</a>).</em></p>
+<p>{div:class=toc}
[TOC]
-{div}
+{div}</p>
+<h2 id="ipojo-instance-lifecycle-lifecycle-controller">iPOJO instance lifecycle & Lifecycle controller</h2>
+<p>Once started, iPOJO instances can be either valid or invalid. The decision comes from handlers. An instance is valid if every plugged handler are valid. Basically it means that all required services are available. As soon as one handler becomes invalid, the instance becomes invalid.</p>
+<p>The lifecycle controller just monitors a field inside the POJO class. When this field becomes <code>false</code>, the handler becomes invalid, and so the instance becomes invalid. When the field get the <code>true</code> value, the handler becomes valid, and if all handlers are valid, the instance becomes valid.</p>
+<h2 id="an-example">An example</h2>
+<p>Imagine the following component :</p>
+<div class="codehilite"><pre><span class="nv">@Component</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">LifecycleControllerTest</span> <span class="p">{</span>
+
+ <span class="nv">@Controller</span>
+ <span class="n">private</span> <span class="n">boolean</span> <span class="n">m_state</span><span class="p">;</span>
+
+ <span class="nv">@Property</span>
+ <span class="n">public</span> <span class="n">void</span> <span class="n">setConf</span><span class="p">(</span><span class="n">String</span> <span class="n">newConf</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">System</span><span class="o">.</span><span class="n">out</span><span class="o">.</span><span class="n">println</span><span class="p">(</span><span class="s">"setConf : "</span> <span class="o">+</span> <span class="n">newConf</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">newConf</span><span class="o">.</span><span class="n">equals</span><span class="p">(</span><span class="s">"a correct value"</span><span class="p">))</span> <span class="p">{</span>
+ <span class="n">m_state</span> <span class="o">=</span> <span class="n">true</span><span class="p">;</span> <span class="sr">//</span> <span class="n">update</span> <span class="n">controller</span> <span class="n">value</span><span class="o">.</span>
+ <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+ <span class="n">m_state</span> <span class="o">=</span> <span class="n">false</span><span class="p">;</span> <span class="sr">//</span> <span class="n">update</span> <span class="n">control</span> <span class="n">value</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>If you don't want to use annotations, the following snippet does the same job using XML:</p>
+<div class="codehilite"><pre><span class="nt"><component</span>
+ <span class="na">classname=</span><span class="s">"org.apache.felix.ipojo.test.scenarios.component.LifecycleControllerTest"</span><span class="nt">></span>
+ <span class="nt"><controller</span> <span class="na">field=</span><span class="s">"m_state"</span><span class="nt">/></span>
+ <span class="nt"><properties></span>
+ <span class="nt"><property</span> <span class="na">name=</span><span class="s">"conf"</span> <span class="na">method=</span><span class="s">"setConf"</span><span class="nt">/></span>
+ <span class="nt"></properties></span>
+<span class="nt"></component></span>
+</pre></div>
-## iPOJO instance lifecycle & Lifecycle controller
-Once started, iPOJO instances can be either valid or invalid. The decision comes from handlers. An instance is valid if every plugged handler are valid. Basically it means that all required services are available. As soon as one handler becomes invalid, the instance becomes invalid.
-
-The lifecycle controller just monitors a field inside the POJO class. When this field becomes `false`, the handler becomes invalid, and so the instance becomes invalid. When the field get the `true` value, the handler becomes valid, and if all handlers are valid, the instance becomes valid.
-
-## An example
-
-Imagine the following component :
-
- @Component
- public class LifecycleControllerTest {
-
- @Controller
- private boolean m_state;
-
- @Property
- public void setConf(String newConf) {
- System.out.println("setConf : " + newConf);
- if (newConf.equals("a correct value")) {
- m_state = true; // update controller value.
- } else {
- m_state = false; // update control value
- }
- }
- }
-
-If you don't want to use annotations, the following snippet does the same job using XML:
-
- <component
- classname="org.apache.felix.ipojo.test.scenarios.component.LifecycleControllerTest">
- <controller field="m_state"/>
- <properties>
- <property name="conf" method="setConf"/>
- </properties>
- </component>
-
-The component requires the `conf` property. iPOJO checks if this property is inside the pushed configuration, but cannot checks if the configuration is correct according to the component semantic. When the instance is created, the `setConf` method is called with the given value. If the given `conf` property is "valid" the `m*state` field (i.e. the controller) is set to `true`. Else, the `m*state` is set to `false`. It means that the lifecycle controller handler becomes invalid and as a consequence, the instance becomes invalid.
+<p>The component requires the <code>conf</code> property. iPOJO checks if this property is inside the pushed configuration, but cannot checks if the configuration is correct according to the component semantic. When the instance is created, the <code>setConf</code> method is called with the given value. If the given <code>conf</code> property is "valid" the <code>m*state</code> field (i.e. the controller) is set to <code>true</code>. Else, the <code>m*state</code> is set to <code>false</code>. It means that the lifecycle controller handler becomes invalid and as a consequence, the instance becomes invalid.</p>
+ </div>
+
+ <img src="http://felix.apache.org/ipojo/site/footer.png" class="footer">
-{include:apache-felix-ipojo-footer}
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1422427 by fmeschbe on Sun, 16 Dec 2012 00:36:51 +0000
+ Rev. 1441864 by fmeschbe on Sun, 3 Feb 2013 06:44:40 +0000
</div>
<div class="trademarkFooter">
Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project
@@ -134,5 +264,18 @@ The component requires the `conf` proper
may be trademarks or registered trademarks of their respective owners.
</div>
</div>
+ </div>
+
+ <script type="text/javascript">
+ var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
+ document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
+ </script>
+ <script type="text/javascript">
+ try{
+ var pageTracker = _gat._getTracker("UA-1518442-4");
+ pageTracker._trackPageview();
+ } catch(err) {}
+ </script>
+
</body>
</html>
Modified: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/event-admin-handlers.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/event-admin-handlers.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/event-admin-handlers.html Sun Feb 3 06:45:21 2013
@@ -20,9 +20,45 @@
<head>
<title>Apache Felix - Event Admin Handlers</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">
+ <link rel="stylesheet" href="/site/media.data/site.css" type="text/css" media="all">
+ <link rel="stylesheet" href="/ipojo/site/superfish.css" type="text/css" media="all">
+ <link rel="stylesheet" href="/ipojo/site/style.css" type="text/css" media="all">
<meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+
+ <!--
+ <script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shCore.js"></script>
+ <script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushCSharp.js"></script>
+ <script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushPhp.js"></script>
+ <script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushJScript.js"></script>
+ <script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushVb.js"></script>
+ <script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushSql.js"></script>
+ <script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushXml.js"></script>
+ <script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushShell.js"></script>
+ <script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushDelphi.js"></script>
+ <script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushPython.js"></script>
+ <script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushJava.js"></script>
+ -->
+
+ <script type="text/javascript" src="/ipojo/site/jquery-1.js"></script>
+ <script type="text/javascript" src="/ipojo/site/hoverIntent.js"></script>
+ <script type="text/javascript" src="/ipojo/site/superfish.js"></script>
+ <script type="text/javascript" src="/ipojo/site/supersubs.js"></script>
+
+ <script type="text/javascript">
+
+ $(document).ready(function(){
+ $("ul.sf-menu").supersubs({
+ minWidth: 14, // minimum width of sub-menus in em units
+ maxWidth: 30, // maximum width of sub-menus in em units
+ extraWidth: 1 // extra width can ensure lines don't sometimes turn over
+ // due to slight rounding differences and font-family
+ }).superfish(); // call supersubs first, then superfish, so that subs are
+ // not display:none when measuring. Call before initialising
+ // containing tabs for same reason.
+ });
+
+ </script>
+
</head>
<body>
<div class="title">
@@ -37,54 +73,148 @@
</a>
</div>
</div>
+
+ <div class="main">
+ <div class="main">
+ <div class="page-header">
+ <img src="/ipojo/site/header.png" class="header">
+ <a href="http://ipojo.org"><img src="/ipojo/site/ipojo.png" width="225" class="header-logo"></a>
+ <ul class="sf-menu sf-js-enabled sf-shadow" id="ipojo-menu">
+ <li class="current">
+ <!-- Menu Overview -->
+ <a href="#" class="sf-with-ul">Overview<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
+ <ul>
+ <li>
+ <a href="">Home</a>
+ </li>
+ <li>
+ <a href="">Why choose iPOJO</a>
+ </li>
+ <li>
+ <a href="">Success stories</a>
+ </li>
+ <li>
+ <a href="">Features</a>
+ </li>
+ </ul>
+ </li>
- <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> <br />
-</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>
+ <li class="">
+ <!-- Menu download -->
+ <li>
+ <a href="/downloads.cgi">Download </a>
+ </li>
- <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-ipojo.html">Apache Felix iPOJO</a> » <a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide.html">apache-felix-ipojo-userguide</a> » <a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components.html">Describing components</a>
- </div>
-
+ <li class="">
+ <!-- Menu Documentation -->
+ <a href="#" class="sf-with-ul">Documentation<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
+ <ul>
+ <!-- sub-menu : getting started -->
+ <li class="">
+ <a href="#" class="sf-with-ul">Getting Started<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
+ <ul>
+ <li><a href="">iPOJO in 10 minutes</a></li>
+ <li><a href="">Using Annotations</a></li>
+ <li><a href="">Maven tutorial</a></li>
+ <li><a href="">Advanced tutorial</a></li>
+ <li><a href="">Using Distributed OSGi</a></li>
+ <li><a href="">Application Composition</a></li>
+ </ul>
+ </li> <!-- end of getting started -->
+ <!-- sub menu : Describing Components -->
+ <li class="">
+ <a href="" class="sf-with-ul">Describing components<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
+ <ul>
+ <li><a href="">Requiring a service</a></li>
+ <li><a href="">Providing a service</a></li>
+ <li><a href="">Lifecycle management</a></li>
+ <li><a href="">Configuration</a></li>
+ <li><a href="">Introspection</a></li>
+ <li><a href="">Impacting the lifecycle</a></li>
+ <li><a href="">Asynchronous communication</a></li>
+ <li><a href="">JMX management</a></li>
+ <li><a href="">Extender pattern</a></li>
+ <li><a href="">Whiteboard pattern</a></li>
+ <li><a href="">Temporal dependencies</a></li>
+ </ul>
+ </li> <!-- End of describing components -->
+ <!-- sub-menu : User Guide -->
+ <li class="">
+ <a href="" class="sf-with-ul">User Guide<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
+ <ul>
+ <li><a href="">iPOJO and config admin</a></li>
+ <li><a href="">Factories and Instances</a></li>
+ <li><a href="">XML Schemas</a></li>
+ <li><a href="">API</a></li>
+ <li><a href="">Testing components</a></li>
+ <li><a href="">Eclipse Integration</a></li>
+ <li><a href="">FAQ</a></li>
+ <li><a href="">Reference Card</a></li>
+ </ul>
+ </li> <!-- end of user guide -->
+ <!-- sub-menu : Dev Guide -->
+ <li>
+ <a href="#" class="sf-with-ul">Advanced Topics<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
+ <ul>
+ <li><a href="http://felix.apache.org/ipojo/api/1.6.0">Javadoc</a></li>
+ <li><a href="">Handler development</a></li>
+ <li><a href="">Manipulation Metadata </a></li>
+ <li><a href="">Dive into the iPOJO Manipulation depths</a></li>
+ </ul>
+ </li> <!-- End of Dev guide -->
+ </ul>
+ </li> <!-- End of doc -->
+ <!-- Menu 4 : Tools -->
+ <li class="">
+ <a href="#" class="sf-with-ul">Tools<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
+ <ul>
+ <li><a href="">Ant Task</a></li>
+ <li><a href="">Eclipse Plugin</a></li>
+ <li><a href="">Maven Plugin</a></li>
+ <li><a href="">`arch` shell command</a></li>
+ <li><a href="">Online Manipulator</a></li>
+ <li><a href="">Webconsole plugin</a></li>
+ <li><a href="">Junit4OSGi</a></li>
+ </ul>
+ </li><!-- End of tools -->
+ <!-- Menu 5 : Support -->
+ <li>
+ <a href="">Support </a>
+ </li>
+ <!-- End of the menu 5 -->
+ <!-- Menu 6 : Misc -->
+ <li class="">
+ <a href="#" class="sf-with-ul">Misc<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
+ <ul>
+ <li><a href="">Supported JVMs</a></li>
+ <li><a href="">Supported OSGi Implementations</a></li>
+ <li><a href="http://ipojo-dark-side.blogspot.com">iPOJO's Dark Side Blog</a></li>
+ <li><a href="">Article & Presentations</a></li>
+ <li><a href="http://www.apache.org/">ASF</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
+ <li><a href="http://www.apache.org/foundation/thanks.html">Sponsors</a></li>
+ </ul>
+ </li><!-- End of misc -->
+ </ul> <!-- End of the menu -->
+ </div> <!-- Page header -->
+
+ <!--
<div class="tip">
This page is a translated version of <a href="/site/event-admin-handlers.html" target="felix_cwiki">/site/event-admin-handlers.html</a>. In case of
doubt you might want to refer to the old page.
</div>
+ -->
<h1>Event Admin Handlers</h1>
- <p>{include:apache-felix-ipojo-header}</p>
-<div class="content">
-
-# Event Admin Handlers
-
-*The goal of the Event Admin Handlers is to allow event communications between iPOJO component instances. The implementation of these handlers relies on an event admin services. It enables the iPOJO component to listen to a list of topics and to receive all related events. It also allows components to send events in an easy way.*
-
-{div:class=toc}
+
+ <div class="content">
+ <h1 id="event-admin-handlers">Event Admin Handlers</h1>
+<p><em>The goal of the Event Admin Handlers is to allow event communications between iPOJO component instances. The implementation of these handlers relies on an event admin services. It enables the iPOJO component to listen to a list of topics and to receive all related events. It also allows components to send events in an easy way.</em></p>
+<p>{div:class=toc}
[TOC]
-{div}
-
+{div}</p>
<div class="info" markdown="1">
**change in the 1.2.0**
The 1.2.0 version use the namespace : `org.apache.felix.ipojo.handlers.event` instead of `org.apache.felix.ipojo.handlers.event.EventAdminHandler`.
@@ -95,238 +225,220 @@ The 1.2.0 version use the namespace : `o
The `@Publisher` annotation is now deprecated and replaced by `@Publishes`.
</div>
-## An example
-Hereafter is presented a small example :
-
- @Component
- @Instantiate
- public class MyComponent {
-
- @Publishes( // or @Publisher before the 1.7.0
- name="myPublisher",
- topics="bar,nuts")
- private Publisher m_publisher;
-
- @Subscriber(
- name="mySubscriber",
- topics="foo")
- public void receive(Event e) {
- // Event received
- // Do something with the event
- }
- }
-
-This component can also be described using the XML formalism:
-
- <ipojo
- xmlns:ev="org.apache.felix.ipojo.handlers.event">
- <component className="...MyComponent">
- <ev:subscriber
- name="mySubscriber"
- callback="receive"
- topics="foo"/>
- <ev:publisher
- name="myPublisher"
- field="m_publisher"
- topics="bar,nuts"/>
- </component>
- <instance component="...MyComponent"/>
- </ipojo>
-
-In XML, you need to specify the namespace of the Handler. You can find here one event subscriber (named mySubscriber) and one event publisher (named myPublisher). In these handler configurations, the name parameter is mandatory. The topics parameter is optional as it can be specified in the instance configuration. The callback parameter of the mySubscriber element is mandatory and indicates the method that handles received events. In this case, this method must have a single argument of type org.osgi.service.event.Event. The field parameter of the myPublisher element indicates the field (of type org.apache.felix.ipojo.handlers.event.publisher.Publisher) that is used by the POJO to send events on the specified topics. All type compliance will be checked by the handler at component instantiation time.
-
-## Download
-
-The event admin handlers (to send and receive events) are available in the Felix trunk in the iPOJO project. See the [Download](/documentation/subprojects/apache-felix-ipojo/download.html) page to download and compile these sources.
-
-## How does it work?
-
-The handler will parse the description provided in the metadata, and register for you the EventHandler in the OSGi Registry. On one hand, your POJO will receive each event through the handler. With this handler you can specify different callback methods for different topics. On the other side, the handler instantiates and injects configured Publisher references in your POJO, so you can send events transparently through these publishers.
-
-## EventHandler Specification
-
-Here you can find all configuration options of the EventAdmin handler. As seen before, the handler contains two components : the event subscriber and the event publisher. These components can be configured, using several attributes, as described below. Some of these attributes can be (re)defined in the instance configuration.
-
-*Handler namespace :* org.apache.felix.ipojo.handlers.event
-
-### Event subscriber attributes
-{div:class=borderedTable}
+<h2 id="an-example">An example</h2>
+<p>Hereafter is presented a small example :</p>
+<div class="codehilite"><pre><span class="nv">@Component</span>
+<span class="nv">@Instantiate</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">MyComponent</span> <span class="p">{</span>
+
+ <span class="nv">@Publishes</span><span class="p">(</span><span class="sr"> //</span> <span class="ow">or</span> <span class="nv">@Publisher</span> <span class="n">before</span> <span class="n">the</span> <span class="mf">1.7.0</span>
+ <span class="n">name</span><span class="o">=</span><span class="s">"myPublisher"</span><span class="p">,</span>
+ <span class="n">topics</span><span class="o">=</span><span class="s">"bar,nuts"</span><span class="p">)</span>
+ <span class="n">private</span> <span class="n">Publisher</span> <span class="n">m_publisher</span><span class="p">;</span>
+
+ <span class="nv">@Subscriber</span><span class="p">(</span>
+ <span class="n">name</span><span class="o">=</span><span class="s">"mySubscriber"</span><span class="p">,</span>
+ <span class="n">topics</span><span class="o">=</span><span class="s">"foo"</span><span class="p">)</span>
+ <span class="n">public</span> <span class="n">void</span> <span class="n">receive</span><span class="p">(</span><span class="n">Event</span> <span class="n">e</span><span class="p">)</span> <span class="p">{</span>
+ <span class="sr">//</span> <span class="n">Event</span> <span class="n">received</span>
+ <span class="sr">//</span> <span class="n">Do</span> <span class="n">something</span> <span class="n">with</span> <span class="n">the</span> <span class="n">event</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>This component can also be described using the XML formalism:</p>
+<div class="codehilite"><pre><span class="nt"><ipojo</span>
+ <span class="na">xmlns:ev=</span><span class="s">"org.apache.felix.ipojo.handlers.event"</span><span class="nt">></span>
+ <span class="nt"><component</span> <span class="na">className=</span><span class="s">"...MyComponent"</span><span class="nt">></span>
+ <span class="nt"><ev:subscriber</span>
+ <span class="na">name=</span><span class="s">"mySubscriber"</span>
+ <span class="na">callback=</span><span class="s">"receive"</span>
+ <span class="na">topics=</span><span class="s">"foo"</span><span class="nt">/></span>
+ <span class="nt"><ev:publisher</span>
+ <span class="na">name=</span><span class="s">"myPublisher"</span>
+ <span class="na">field=</span><span class="s">"m_publisher"</span>
+ <span class="na">topics=</span><span class="s">"bar,nuts"</span><span class="nt">/></span>
+ <span class="nt"></component></span>
+ <span class="nt"><instance</span> <span class="na">component=</span><span class="s">"...MyComponent"</span><span class="nt">/></span>
+<span class="nt"></ipojo></span>
+</pre></div>
+
+
+<p>In XML, you need to specify the namespace of the Handler. You can find here one event subscriber (named mySubscriber) and one event publisher (named myPublisher). In these handler configurations, the name parameter is mandatory. The topics parameter is optional as it can be specified in the instance configuration. The callback parameter of the mySubscriber element is mandatory and indicates the method that handles received events. In this case, this method must have a single argument of type org.osgi.service.event.Event. The field parameter of the myPublisher element indicates the field (of type org.apache.felix.ipojo.handlers.event.publisher.Publisher) that is used by the POJO to send events on the specified topics. All type compliance will be checked by the handler at component instantiation time.</p>
+<h2 id="download">Download</h2>
+<p>The event admin handlers (to send and receive events) are available in the Felix trunk in the iPOJO project. See the <a href="/documentation/subprojects/apache-felix-ipojo/download.html">Download</a> page to download and compile these sources.</p>
+<h2 id="how-does-it-work">How does it work?</h2>
+<p>The handler will parse the description provided in the metadata, and register for you the EventHandler in the OSGi Registry. On one hand, your POJO will receive each event through the handler. With this handler you can specify different callback methods for different topics. On the other side, the handler instantiates and injects configured Publisher references in your POJO, so you can send events transparently through these publishers.</p>
+<h2 id="eventhandler-specification">EventHandler Specification</h2>
+<p>Here you can find all configuration options of the EventAdmin handler. As seen before, the handler contains two components : the event subscriber and the event publisher. These components can be configured, using several attributes, as described below. Some of these attributes can be (re)defined in the instance configuration.</p>
+<p><em>Handler namespace :</em> org.apache.felix.ipojo.handlers.event</p>
+<h3 id="event-subscriber-attributes">Event subscriber attributes</h3>
+<p>{div:class=borderedTable}
| Attribute name | Required | Description |
|--|--|--|
-| *name* | YES | The name of the event subscriber, acting as a unique identifier. |
-| *callback* | YES | The name of the POJO's method that will be called each time an event is received. This method takes only one parameter, of typeorg.osgi.service.event.Eventby default, but this type can be overridden by defining the data-key and/or the data-type attributes. |
-| *topics* | YES\* | The comma-separated-list of the topics that the handler will listen to. Each event sent on a topic present in this list will be sent to the specified callback method. |
-
-If an event is received and it does not contain such a key, it is ignored (with a warning message). |
-
-Data events that are not corresponding to the specified type will be ignored (with a warning message). |
-| *filter* | NO\* | The event filter is used to filter incoming events before sending them to the callback. The syntax of this field is described in the OSGi EventAdmin Specification. If you don't specify a filter, all events sent on the listened topics will be considered. |
-\* These attributes can be (re)defined in the instance configuration.
-{div}
-### Event publisher attributes
-{div:class=borderedTable}
+| <em>name</em> | YES | The name of the event subscriber, acting as a unique identifier. |
+| <em>callback</em> | YES | The name of the POJO's method that will be called each time an event is received. This method takes only one parameter, of typeorg.osgi.service.event.Eventby default, but this type can be overridden by defining the data-key and/or the data-type attributes. |
+| <em>topics</em> | YES* | The comma-separated-list of the topics that the handler will listen to. Each event sent on a topic present in this list will be sent to the specified callback method. |</p>
+<p>If an event is received and it does not contain such a key, it is ignored (with a warning message). |</p>
+<p>Data events that are not corresponding to the specified type will be ignored (with a warning message). |
+| <em>filter</em> | NO* | The event filter is used to filter incoming events before sending them to the callback. The syntax of this field is described in the OSGi EventAdmin Specification. If you don't specify a filter, all events sent on the listened topics will be considered. |
+* These attributes can be (re)defined in the instance configuration.
+{div}</p>
+<h3 id="event-publisher-attributes">Event publisher attributes</h3>
+<p>{div:class=borderedTable}
| Attribute name | Required | Description |
|--|--|--|
-| *name* | YES | The name of the event publisher, acting as a unique identifier. |
-| *field* | YES | The name of the POJO's field that will be used to send events. The field is initialized at component instantiation time. The type of the field must be : org.apache.felix.ipojo.handlers.event.publisher.Publisher. Despite it creates a dependency between the component code and the handler, this system allows hiding the whole complexity of event sending. |
-| *topics* | YES\* | The comma-separated-list of the topics on which events will be sent. |
-
-The default value of this attribute is user.data. |
-
-The default value of this attribute is "false". |
-\* These attributes can be (re)defined in the instance configuration.
-{div}
-### Instance configuration
-
-Some of the described attributes can be (re)defined in the instance configuration section of your metadata file. Its permits to configure event management instance by instance. The following properties are used by the handler :
-* *event.topics* : overrides *topics* attribute, available for both subscribers and publishers configuration
-* *event.filter* : overrides *filter* attribute, available for subscribers configuration only.
-
-### Publisher interface
-
-The Publisher interface is the link between the component code and the handler. It permits to publish events on the topics specified in the component's description (or instance configuration). The implemented methods are :
-* public void send{color:#000000}(Dictionary content);{color}
+| <em>name</em> | YES | The name of the event publisher, acting as a unique identifier. |
+| <em>field</em> | YES | The name of the POJO's field that will be used to send events. The field is initialized at component instantiation time. The type of the field must be : org.apache.felix.ipojo.handlers.event.publisher.Publisher. Despite it creates a dependency between the component code and the handler, this system allows hiding the whole complexity of event sending. |
+| <em>topics</em> | YES* | The comma-separated-list of the topics on which events will be sent. |</p>
+<p>The default value of this attribute is user.data. |</p>
+<p>The default value of this attribute is "false". |
+* These attributes can be (re)defined in the instance configuration.
+{div}</p>
+<h3 id="instance-configuration">Instance configuration</h3>
+<p>Some of the described attributes can be (re)defined in the instance configuration section of your metadata file. Its permits to configure event management instance by instance. The following properties are used by the handler :
+<em> </em>event.topics<em> : overrides </em>topics<em> attribute, available for both subscribers and publishers configuration
+</em> <em>event.filter</em> : overrides <em>filter</em> attribute, available for subscribers configuration only.</p>
+<h3 id="publisher-interface">Publisher interface</h3>
+<p>The Publisher interface is the link between the component code and the handler. It permits to publish events on the topics specified in the component's description (or instance configuration). The implemented methods are :
+<em> public void send{color:#000000}(Dictionary content);{color}
This method is used to send a standard event, with the specified content. Some specific properties may be added in the content to satisfy EventAdmin specification. (e.g., event.topic).
-* public void sendData{color:#000000}(Object o);{color}
-This method is the easier way to send data. The given object is placed in the event dictionary according to the *data-key* attribute (or its default value). Then, this dictionary is sent as a normal event.
-
-## Handler Architecture
-
-Here is shown the global architecture of the EventHandler : the interactions between the user components (i.e., POJO), the handler and the OSGi runtime environment.
-
-!handler-arch.png!
-
-## EventHandler Features
-In this section, you will find some examples of the handler's features.
-
-### Instance customization
-As described in the 'Instance configuration' section, you can (re)define some of the subscribers or publishers attributes. You can notice that required attributes that are not defined in the component description must be defined in the instance configuration section. Hereafter is an example of an instance configuration of this handler :
-
- <ipojo>
- <instance component="...MyComponent">
- <property name="event.topics">
- <property name="mySubscriber" value="foo"/>
- <property name="myPublisher" value="bar,nuts"/>
- </property>
- <property name="event.filter">
- <property name="mySubscriber"
- value="|((arg=Minibar)(arg=Coconuts))"/>
- </property>
- </instance>
- </ipojo>
-
-### Data events
-One of the most important features of the EventHandler is the capability of sending and receiving data events. You may know that the OSGi EventAdmin Service allows bundles to send custom objects in events, inserting them in the event's dictionary. The EventHandler hides the dictionary manipulation and allows iPOJO components to receive custom objects at any time.
-
-First, you have define the *data-key* attribute in the publisher configuration (`dataKey` in annotations). Sent objects will be contained in the event dictionary and are accessible with the "user.data" key.
-
- <ipojo
- xmlns:ev="org.apache.felix.ipojo.handlers.event">
- <component className="...DataPublisher">
- <ev:publisher
- name="myPublisher"
- field="m_publisher"
- topics="myTopic"
- data-key="my.data"/>
- </component>
- <instance component="...DataPublisher"/>
- </ipojo>
-
-Then you can use the *sendData* method of your configured publisher.
-
- import org.apache.felix.ipojo.handlers.event.publisher.Publisher;
- //...
- public class DataPublisher ... {
- private Publisher m_publisher;
-
- public void doSomething() {
- // MyFavoriteType extends MyFavoriteInterface
- MyFavoriteType data = new MyFavoriteType(...);
- //...
- // Send a data event
- m_publisher.sendData(data);
- }
- }
-
-The second step is to configure an event subscriber to receive such events. The *data-key* attribute's value of the subscriber must be the same than the publisher's one. The *data-type* describes the type of received data events, and thus, must be compatible with the sent object's type (i.e., super-class or inherited interface). Then you can finally receive the sent object in the callback method. The parameter type of the callback must be the same than the data-type attribute value.
-
- <ipojo
- xmlns:ev="org.apache.felix.ipojo.handlers.event">
- <component className="...DataEventSubscriber">
- <ev:subscriber
- name="mySubscriber"
- callback="handleData"
- topics="myTopic"
- data-key="my.data"
- data-type="my.package.MyFavoriteInterface"/>
- </component>
- <instance component="...DataEventSubscriber"/>
- </ipojo>
-
- import my.package.MyFavoriteInterface;
- //...
- public class DataEventSubscriber ... {
- public void handleData(MyFavoriteInterface o) {
- // Object received
- //...
- }
- }
-
-Annotations use a different set of attributes:
-* data-key is replaced by `dataKey`
-* data-type is replaced by `dataType`
-
-### Note on synchronous event sending
-
-By default, events are sent using asynchronous sending (a.k.a.*post* in OSGi EventAdmin). You can use synchronous sending by defining the *synchronous* attribute of your publisher to true.
-
-The behavior of synchronous event sending is particular when you specify several topics in the publisher description. The event is synchronously sent to each topic, one by one. So when you return from this function, you can be sure that the event has been delivered to each topic.
-
-### Publisher instance information
-
-All events sent by a publisher contains the name of the component instance that sent them. Its enables to filter received events depending the sender instance. The instance name is accessible in the event dictionary by the key *publisher.instance.name*. Despite it goes against MOM principles, this property is useful to trace events and especially event sources.
+</em> public void sendData{color:#000000}(Object o);{color}
+This method is the easier way to send data. The given object is placed in the event dictionary according to the <em>data-key</em> attribute (or its default value). Then, this dictionary is sent as a normal event.</p>
+<h2 id="handler-architecture">Handler Architecture</h2>
+<p>Here is shown the global architecture of the EventHandler : the interactions between the user components (i.e., POJO), the handler and the OSGi runtime environment.</p>
+<p>!handler-arch.png!</p>
+<h2 id="eventhandler-features">EventHandler Features</h2>
+<p>In this section, you will find some examples of the handler's features.</p>
+<h3 id="instance-customization">Instance customization</h3>
+<p>As described in the 'Instance configuration' section, you can (re)define some of the subscribers or publishers attributes. You can notice that required attributes that are not defined in the component description must be defined in the instance configuration section. Hereafter is an example of an instance configuration of this handler :</p>
+<div class="codehilite"><pre><span class="nt"><ipojo></span>
+ <span class="nt"><instance</span> <span class="na">component=</span><span class="s">"...MyComponent"</span><span class="nt">></span>
+ <span class="nt"><property</span> <span class="na">name=</span><span class="s">"event.topics"</span><span class="nt">></span>
+ <span class="nt"><property</span> <span class="na">name=</span><span class="s">"mySubscriber"</span> <span class="na">value=</span><span class="s">"foo"</span><span class="nt">/></span>
+ <span class="nt"><property</span> <span class="na">name=</span><span class="s">"myPublisher"</span> <span class="na">value=</span><span class="s">"bar,nuts"</span><span class="nt">/></span>
+ <span class="nt"></property></span>
+ <span class="nt"><property</span> <span class="na">name=</span><span class="s">"event.filter"</span><span class="nt">></span>
+ <span class="nt"><property</span> <span class="na">name=</span><span class="s">"mySubscriber"</span>
+ <span class="na">value=</span><span class="s">"|((arg=Minibar)(arg=Coconuts))"</span><span class="nt">/></span>
+ <span class="nt"></property></span>
+ <span class="nt"></instance></span>
+<span class="nt"></ipojo></span>
+</pre></div>
+
+
+<h3 id="data-events">Data events</h3>
+<p>One of the most important features of the EventHandler is the capability of sending and receiving data events. You may know that the OSGi EventAdmin Service allows bundles to send custom objects in events, inserting them in the event's dictionary. The EventHandler hides the dictionary manipulation and allows iPOJO components to receive custom objects at any time.</p>
+<p>First, you have define the <em>data-key</em> attribute in the publisher configuration (<code>dataKey</code> in annotations). Sent objects will be contained in the event dictionary and are accessible with the "user.data" key. </p>
+<div class="codehilite"><pre><span class="nt"><ipojo</span>
+ <span class="na">xmlns:ev=</span><span class="s">"org.apache.felix.ipojo.handlers.event"</span><span class="nt">></span>
+ <span class="nt"><component</span> <span class="na">className=</span><span class="s">"...DataPublisher"</span><span class="nt">></span>
+ <span class="nt"><ev:publisher</span>
+ <span class="na">name=</span><span class="s">"myPublisher"</span>
+ <span class="na">field=</span><span class="s">"m_publisher"</span>
+ <span class="na">topics=</span><span class="s">"myTopic"</span>
+ <span class="na">data-key=</span><span class="s">"my.data"</span><span class="nt">/></span>
+ <span class="nt"></component></span>
+ <span class="nt"><instance</span> <span class="na">component=</span><span class="s">"...DataPublisher"</span><span class="nt">/></span>
+<span class="nt"></ipojo></span>
+</pre></div>
+
+
+<p>Then you can use the <em>sendData</em> method of your configured publisher.</p>
+<div class="codehilite"><pre><span class="nb">import</span> <span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">felix</span><span class="o">.</span><span class="n">ipojo</span><span class="o">.</span><span class="n">handlers</span><span class="o">.</span><span class="n">event</span><span class="o">.</span><span class="n">publisher</span><span class="o">.</span><span class="n">Publisher</span><span class="p">;</span>
+<span class="sr">//</span><span class="o">...</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">DataPublisher</span> <span class="o">...</span> <span class="p">{</span>
+ <span class="n">private</span> <span class="n">Publisher</span> <span class="n">m_publisher</span><span class="p">;</span>
+
+ <span class="n">public</span> <span class="n">void</span> <span class="n">doSomething</span><span class="p">()</span> <span class="p">{</span>
+ <span class="sr">//</span> <span class="n">MyFavoriteType</span> <span class="n">extends</span> <span class="n">MyFavoriteInterface</span>
+ <span class="n">MyFavoriteType</span> <span class="n">data</span> <span class="o">=</span> <span class="k">new</span> <span class="n">MyFavoriteType</span><span class="p">(</span><span class="o">...</span><span class="p">);</span>
+ <span class="sr">//</span><span class="o">...</span>
+ <span class="sr">//</span> <span class="n">Send</span> <span class="n">a</span> <span class="n">data</span> <span class="n">event</span>
+ <span class="n">m_publisher</span><span class="o">.</span><span class="n">sendData</span><span class="p">(</span><span class="n">data</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>The second step is to configure an event subscriber to receive such events. The <em>data-key</em> attribute's value of the subscriber must be the same than the publisher's one. The <em>data-type</em> describes the type of received data events, and thus, must be compatible with the sent object's type (i.e., super-class or inherited interface). Then you can finally receive the sent object in the callback method. The parameter type of the callback must be the same than the data-type attribute value.</p>
+<div class="codehilite"><pre><span class="nt"><ipojo</span>
+ <span class="na">xmlns:ev=</span><span class="s">"org.apache.felix.ipojo.handlers.event"</span><span class="nt">></span>
+ <span class="nt"><component</span> <span class="na">className=</span><span class="s">"...DataEventSubscriber"</span><span class="nt">></span>
+ <span class="nt"><ev:subscriber</span>
+ <span class="na">name=</span><span class="s">"mySubscriber"</span>
+ <span class="na">callback=</span><span class="s">"handleData"</span>
+ <span class="na">topics=</span><span class="s">"myTopic"</span>
+ <span class="na">data-key=</span><span class="s">"my.data"</span>
+ <span class="na">data-type=</span><span class="s">"my.package.MyFavoriteInterface"</span><span class="nt">/></span>
+ <span class="nt"></component></span>
+ <span class="nt"><instance</span> <span class="na">component=</span><span class="s">"...DataEventSubscriber"</span><span class="nt">/></span>
+<span class="nt"></ipojo></span>
+
+import my.package.MyFavoriteInterface;
+//...
+public class DataEventSubscriber ... {
+ public void handleData(MyFavoriteInterface o) {
+ // Object received
+ //...
+ }
+}
+</pre></div>
-### Configuring the handler with annotations
-It is possible to configure the handler with a simple annotations available in the annotation pack ('annotation' project in the iPOJO trunk). Here is an example of usage:
+<p>Annotations use a different set of attributes:
+<em> data-key is replaced by <code>dataKey</code>
+</em> data-type is replaced by <code>dataType</code></p>
+<h3 id="note-on-synchronous-event-sending">Note on synchronous event sending</h3>
+<p>By default, events are sent using asynchronous sending (a.k.a.<em>post</em> in OSGi EventAdmin). You can use synchronous sending by defining the <em>synchronous</em> attribute of your publisher to true.</p>
+<p>The behavior of synchronous event sending is particular when you specify several topics in the publisher description. The event is synchronously sent to each topic, one by one. So when you return from this function, you can be sure that the event has been delivered to each topic.</p>
+<h3 id="publisher-instance-information">Publisher instance information</h3>
+<p>All events sent by a publisher contains the name of the component instance that sent them. Its enables to filter received events depending the sender instance. The instance name is accessible in the event dictionary by the key <em>publisher.instance.name</em>. Despite it goes against MOM principles, this property is useful to trace events and especially event sources.</p>
+<h3 id="configuring-the-handler-with-annotations">Configuring the handler with annotations</h3>
+<p>It is possible to configure the handler with a simple annotations available in the annotation pack ('annotation' project in the iPOJO trunk). Here is an example of usage:
{code:java}
import org.apache.felix.ipojo.annotations.Component;
import org.apache.felix.ipojo.handlers.event.Subscriber;
import org.apache.felix.ipojo.handlers.event.Publishes
import org.apache.felix.ipojo.handlers.event.Publisher;
-import org.osgi.service.event.Event;
-
-@Component
+import org.osgi.service.event.Event;</p>
+<p>@Component
public class PubSub {
@Publishes(name="p1", synchronous=true)
- Publisher publisher1;
-
- @Publishes(name="p2", synchronous=false, topics="foo,bar", data_key="data")
- Publisher publisher2;
-
- @Publishes(name="p3", synchronous=true, topics="bar")
- Publisher publisher3;
-
- @Subscriber(name="s1", data_key="data")
- public void receive1(Object foo) {
- // Process event
- }
-
- @Subscriber(name="s2", topics="foo,bar", filter="(foo=true)")
- public void receive2(Event foo) {
- // Process event
- }
-
- @Subscriber(name="s3", topics="foo", data*key="data", data*type="java.lang.String")
- public void receive3(String foo) {
- // Process event
- }
-}
+ Publisher publisher1;</p>
+<div class="codehilite"><pre><span class="nv">@Publishes</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">"p2"</span><span class="p">,</span> <span class="n">synchronous</span><span class="o">=</span><span class="n">false</span><span class="p">,</span> <span class="n">topics</span><span class="o">=</span><span class="s">"foo,bar"</span><span class="p">,</span> <span class="n">data_key</span><span class="o">=</span><span class="s">"data"</span><span class="p">)</span>
+<span class="n">Publisher</span> <span class="n">publisher2</span><span class="p">;</span>
+
+<span class="nv">@Publishes</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">"p3"</span><span class="p">,</span> <span class="n">synchronous</span><span class="o">=</span><span class="n">true</span><span class="p">,</span> <span class="n">topics</span><span class="o">=</span><span class="s">"bar"</span><span class="p">)</span>
+<span class="n">Publisher</span> <span class="n">publisher3</span><span class="p">;</span>
+
+<span class="nv">@Subscriber</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">"s1"</span><span class="p">,</span> <span class="n">data_key</span><span class="o">=</span><span class="s">"data"</span><span class="p">)</span>
+<span class="n">public</span> <span class="n">void</span> <span class="n">receive1</span><span class="p">(</span><span class="n">Object</span> <span class="n">foo</span><span class="p">)</span> <span class="p">{</span>
+ <span class="sr">//</span> <span class="n">Process</span> <span class="n">event</span>
+<span class="p">}</span>
+
+<span class="nv">@Subscriber</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">"s2"</span><span class="p">,</span> <span class="n">topics</span><span class="o">=</span><span class="s">"foo,bar"</span><span class="p">,</span> <span class="n">filter</span><span class="o">=</span><span class="s">"(foo=true)"</span><span class="p">)</span>
+<span class="n">public</span> <span class="n">void</span> <span class="n">receive2</span><span class="p">(</span><span class="n">Event</span> <span class="n">foo</span><span class="p">)</span> <span class="p">{</span>
+ <span class="sr">//</span> <span class="n">Process</span> <span class="n">event</span>
+<span class="p">}</span>
+
+<span class="nv">@Subscriber</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">"s3"</span><span class="p">,</span> <span class="n">topics</span><span class="o">=</span><span class="s">"foo"</span><span class="p">,</span> <span class="n">data</span><span class="o">*</span><span class="n">key</span><span class="o">=</span><span class="s">"data"</span><span class="p">,</span> <span class="n">data</span><span class="o">*</span><span class="n">type</span><span class="o">=</span><span class="s">"java.lang.String"</span><span class="p">)</span>
+<span class="n">public</span> <span class="n">void</span> <span class="n">receive3</span><span class="p">(</span><span class="n">String</span> <span class="n">foo</span><span class="p">)</span> <span class="p">{</span>
+ <span class="sr">//</span> <span class="n">Process</span> <span class="n">event</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>}</p>
+<div class="codehilite"><pre><span class="o">\\</span>
+</pre></div>
+ </div>
+
+ <img src="http://felix.apache.org/ipojo/site/footer.png" class="footer">
- \\
- {include:apache-felix-ipojo-footer}
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1422427 by fmeschbe on Sun, 16 Dec 2012 00:36:51 +0000
+ Rev. 1441864 by fmeschbe on Sun, 3 Feb 2013 06:44:40 +0000
</div>
<div class="trademarkFooter">
Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project
@@ -334,5 +446,18 @@ public class PubSub {
may be trademarks or registered trademarks of their respective owners.
</div>
</div>
+ </div>
+
+ <script type="text/javascript">
+ var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
+ document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
+ </script>
+ <script type="text/javascript">
+ try{
+ var pageTracker = _gat._getTracker("UA-1518442-4");
+ pageTracker._trackPageview();
+ } catch(err) {}
+ </script>
+
</body>
</html>