Update doc
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@796268 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/ipojo/handler/eventadmin/doc/event-admin-handlers.html b/ipojo/handler/eventadmin/doc/event-admin-handlers.html
index 783515a..b9fc56e 100644
--- a/ipojo/handler/eventadmin/doc/event-admin-handlers.html
+++ b/ipojo/handler/eventadmin/doc/event-admin-handlers.html
@@ -12,49 +12,243 @@
<ul>
<li><a href="http://felix.apache.org/site/news.html" title="news">news</a></li>
<li><a href="http://felix.apache.org/site/license.html" title="license">license</a></li>
- <li><span class="nobr"><a href="http://felix.apache.org/site/downloads.cgi" title="Visit page outside Confluence" rel="nofollow">downloads<sup><img class="rendericon" src="event-admin-handlers_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
+ <li><a href="http://felix.apache.org/site/downloads.cgi" rel="nofollow">downloads</a></li>
<li><a href="http://felix.apache.org/site/documentation.html" title="documentation">documentation</a></li>
<li><a href="http://felix.apache.org/site/mailinglists.html" title="mailinglists">mailing lists</a></li>
<li><a href="http://felix.apache.org/site/contributing.html" title="Contributing">contributing</a></li>
- <li><span class="nobr"><a href="http://www.apache.org/" title="Visit page outside Confluence" rel="nofollow">asf<sup><img class="rendericon" src="event-admin-handlers_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
- <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="event-admin-handlers_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
- <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="event-admin-handlers_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span>
+ <li><a href="http://www.apache.org/" rel="nofollow">asf</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html" rel="nofollow">sponsorship</a></li>
+ <li><a href="http://www.apache.org/foundation/thanks.html" rel="nofollow">sponsors</a>
<!-- ApacheCon Ad -->
-<iframe src="event-admin-handlers_files/button.html" style="border-width: 0pt; float: left;" scrolling="no" width="135" frameborder="0" height="135"></iframe>
+<iframe src="event-admin-handlers_files/button.html" style="border-width: 0pt; float: left;" scrolling="no" frameborder="0" height="135" width="135"></iframe>
<p style="height: 100px;">
<!-- ApacheCon Ad -->
</p></li></ul> </div>
<div class="main">
-<table class="sectionMacro" border="0" cellpadding="5" cellspacing="0" width="100%"><tbody><tr>
-<td class="confluenceTd" valign="top" width="80%">
+<style type="text/css">
+ @import url(http://people.apache.org/~clement/ipojo/site/superfish.css);
+</style>
+
+<style type="text/css">
+ @import url(http://people.apache.org/~clement/ipojo/site/style.css);
+</style>
+
+<p>
+<script class="javascript" src="event-admin-handlers_files/shCore.js"></script>
+<script class="javascript" src="event-admin-handlers_files/shBrushCSharp.js"></script>
+<script class="javascript" src="event-admin-handlers_files/shBrushPhp.js"></script>
+<script class="javascript" src="event-admin-handlers_files/shBrushJScript.js"></script>
+<script class="javascript" src="event-admin-handlers_files/shBrushVb.js"></script>
+<script class="javascript" src="event-admin-handlers_files/shBrushSql.js"></script>
+<script class="javascript" src="event-admin-handlers_files/shBrushXml.js"></script>
+<script class="javascript" src="event-admin-handlers_files/shBrushShell.js"></script>
+<script class="javascript" src="event-admin-handlers_files/shBrushDelphi.js"></script>
+<script class="javascript" src="event-admin-handlers_files/shBrushPython.js"></script>
+<script class="javascript" src="event-admin-handlers_files/shBrushJava.js"></script>
+
+<script type="text/javascript" src="event-admin-handlers_files/jquery-1.js"></script>
+<script type="text/javascript" src="event-admin-handlers_files/hoverIntent.js"></script>
+<script type="text/javascript" src="event-admin-handlers_files/superfish.js"></script>
+<script type="text/javascript" src="event-admin-handlers_files/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>
+</p><div class="main">
+<div class="page-header">
+<img src="event-admin-handlers_files/header.png" class="header">
+<a href="http://ipojo.org/"><img src="event-admin-handlers_files/ipojo.png" class="header-logo" width="225"></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><span class="sf-sub-indicator"> »</span></a>
+<ul style="float: none; width: 14em; display: none; visibility: hidden;">
+ <li style="white-space: normal; float: left; width: 100%;">
+ <a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo.html" title="Apache Felix iPOJO">Home</a>
+ </li>
+ <li style="white-space: normal; float: left; width: 100%;">
+ <a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-why-choose-ipojo.html" title="apache-felix-ipojo-why-choose-ipojo">Why choose iPOJO</a>
+ </li>
+ <li style="white-space: normal; float: left; width: 100%;">
+ <a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-successstories.html" title="apache-felix-ipojo-successstories">Success stories</a>
+ </li>
+ <li style="white-space: normal; float: left; width: 100%;">
+ <a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-feature-overview.html" title="Apache Felix iPOJO Feature Overview">Features</a>
+ </li>
+</ul>
+</li>
+
+<li class="">
+<!-- Menu download -->
+</li><li>
+<a href="http://felix.apache.org/site/download.html" title="Download">Download </a>
+</li>
+
+<li class="">
+<!-- Menu Documentation -->
+<a href="" class="sf-with-ul">Documentation<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
+<ul style="float: none; width: 14em; display: none; visibility: hidden;">
+ <!-- sub- menu : getting started -->
+ <li style="white-space: normal; float: left; width: 100%;" class="">
+ <a style="float: none; width: auto;" href="" class="sf-with-ul">Getting Started<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
+ <ul style="left: 14em; float: none; width: 14em; display: none; visibility: hidden;">
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/ipojo-in-10-minutes.html" title="iPOJO in 10 minutes">iPOJO in 10 minutes</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/how-to-use-ipojo-annotations.html" title="How to use iPOJO Annotations">Using Annotations</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/ipojo-hello-word-maven-based-tutorial.html" title="iPOJO Hello Word (Maven-Based) tutorial">Maven tutorial</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/ipojo-advanced-tutorial.html" title="iPOJO Advanced Tutorial">Advanced tutorial</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-dosgi.html" title="apache-felix-ipojo-dosgi">Using Distributed OSGi</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/ipojo-composition-tutorial.html" title="iPOJO Composition Tutorial">Application Composition</a></li>
+ </ul>
+ </li> <!-- end of getting started -->
+ <!-- sub menu : Describing Components -->
+ <li style="white-space: normal; float: left; width: 100%;" class="">
+ <a style="float: none; width: auto;" href="http://felix.apache.org/site/describing-components.html" class="sf-with-ul">Describing components<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
+ <ul style="left: 14em; float: none; width: 14em; display: none; visibility: hidden;">
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/service-requirement-handler.html" title="Service Requirement Handler">Requiring a service</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/providing-osgi-services.html" title="Providing OSGi services">Providing a service</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/lifecycle-callback-handler.html" title="Lifecycle Callback Handler">Lifecycle management</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/configuration-handler.html" title="Configuration Handler">Configuration</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/architecture-handler.html" title="Architecture Handler">Introspection</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/controller-lifecycle-handler.html" title="Controller Lifecycle Handler">Impacting the lifecycle</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="" title="Event Admin Handlers">Asynchronous communication</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/ipojo-jmx-handler.html" title="iPOJO JMX Handler">JMX management</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/extender-pattern-handler.html" title="Extender Pattern Handler">Extender pattern</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/white-board-pattern-handler.html" title="White Board Pattern Handler">Whiteboard pattern</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/temporal-service-dependency.html" title="Temporal Service Dependency">Temporal dependencies</a></li>
+ </ul>
+ </li> <!-- End of describing components -->
+ <!-- sub- menu : User Guide -->
+ <li style="white-space: normal; float: left; width: 100%;" class="">
+ <a style="float: none; width: auto;" href="" class="sf-with-ul">User Guide<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
+ <ul style="left: 14em; float: none; width: 14em; display: none; visibility: hidden;">
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/using-xml-schemas.html" title="Using XML Schemas">XML Schemas</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-api.html" title="apache-felix-ipojo-api">API</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-testing-components.html" title="apache-felix-ipojo-testing-components">Testing components</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-eclipse-integration.html" title="apache-felix-ipojo-eclipse-integration">Eclipse Integration</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/ipojo-faq.html" title="iPOJO FAQ">FAQ</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/ipojo-reference-card.html" title="iPOJO-Reference-Card">Reference Card</a></li>
+ </ul>
+ </li> <!-- end of user guide -->
+ <!-- sub- menu : Dev Guide -->
+ <li class="" style="white-space: normal; float: left; width: 100%;">
+ <a style="float: none; width: auto;" href="" class="sf-with-ul">Advanced Topics<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
+ <ul style="left: 14em; float: none; width: 14em; display: none; visibility: hidden;">
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/ipojo/api/1.2.0" rel="nofollow">Javadoc</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/how-to-write-your-own-handler.html" title="How to write your own handler">Handler guide</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/how-to-use-ipojo-manipulation-metadata.html" title="How to use iPOJO Manipulation Metadata">Manipulation Metadata </a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/dive-into-the-ipojo-manipulation-depths.html" title="Dive into the iPOJO Manipulation depths">Dive into the iPOJO Manipulation depths</a></li>
+ </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><span class="sf-sub-indicator"> »</span></a>
+<ul style="float: none; width: 14em; display: none; visibility: hidden;">
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/ipojo-ant-task.html" title="iPOJO Ant Task">Ant Task</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/ipojo-eclipse-plug-in.html" title="iPOJO Eclipse Plug-in">Eclipse Plugin</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/ipojo-maven-plug-in.html" title="iPOJO Maven Plug-in">Maven Plugin</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-online-manipulator.html" title="apache-felix-ipojo-online-manipulator">Online Manipulator</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/ipojo-webconsole-plugin.html" title="iPOJO Webconsole Plugin">Webconsole plugin</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-junit4osgi.html" title="apache-felix-ipojo-junit4osgi">Junit4OSGi</a></li>
+</ul>
+</li><!-- End of tools -->
+<!-- Menu 5 : Misc -->
+<li class="">
+<a href="" class="sf-with-ul">Misc<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator"> »</span></a>
+<ul style="float: none; width: 14em; display: none; visibility: hidden;">
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-issuestracker.html" title="apache-felix-ipojo-issuestracker">Issues Tracker</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-supportedvms.html" title="apache-felix-ipojo-supportedVMs">Supported JVMs</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/apache-felix-ipojo-supportedosgi.html" title="apache-felix-ipojo-supportedOSGi">Supported OSGi Implementations</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://ipojo-dark-side.blogspot.com/" rel="nofollow">iPOJO's Dark Side Blog</a></li>
+ <li style="white-space: normal; float: left; width: 100%;"><a style="float: none; width: auto;" href="http://felix.apache.org/site/article-presentations.html" title="Article & Presentations">Article & Presentations</a></li>
+</ul>
+</li><!-- End of misc -->
+</ul> <!-- End of the menu -->
+</div> <!-- Page header -->
+
+
+<div class="content">
+
<h1><a name="EventAdminHandlers-EventAdminHandlers"></a>Event Admin Handlers</h1>
-<p>The goal of the Event Admin Handlers is to allow event
+<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
-event. It also allows components to send events in an easy way.</p>
+event. It also allows components to send events in an easy way.</em></p>
-<p><b>UPDATE</b> : the 1.1.0-SNAPSHOT version has a new namespace : <tt>org.apache.felix.ipojo.handlers.event</tt> instead of <tt>org.apache.felix.ipojo.handlers.event.EventAdminHandler</tt></p>
+<div class="toc">
+<ul>
+ <li><a href="#EventAdminHandlers-Anexample">An example</a></li>
+ <li><a href="#EventAdminHandlers-Download">Download</a></li>
+ <li><a href="#EventAdminHandlers-Howdoesitwork%253F">How does it work?</a></li>
+ <li><a href="#EventAdminHandlers-EventHandlerSpecification">EventHandler Specification</a></li>
+<ul>
+ <li><a href="#EventAdminHandlers-Eventsubscriberattributes">Event subscriber attributes</a></li>
+ <li><a href="#EventAdminHandlers-Eventpublisherattributes">Event publisher attributes</a></li>
+ <li><a href="#EventAdminHandlers-Instanceconfiguration">Instance configuration</a></li>
+ <li><a href="#EventAdminHandlers-Publisherinterface">Publisher interface</a></li>
+</ul>
+ <li><a href="#EventAdminHandlers-HandlerArchitecture">Handler Architecture</a></li>
+ <li><a href="#EventAdminHandlers-EventHandlerFeatures">EventHandler Features</a></li>
+<ul>
+ <li><a href="#EventAdminHandlers-Instancecustomization">Instance customization</a></li>
+ <li><a href="#EventAdminHandlers-Dataevents">Data events</a></li>
+ <li><a href="#EventAdminHandlers-Noteonsynchronouseventsending">Note on synchronous event sending</a></li>
+ <li><a href="#EventAdminHandlers-Publisherinstanceinformation">Publisher instance information</a></li>
+ <li><a href="#EventAdminHandlers-Configuringthehandlerwithannotations">Configuring the handler with annotations</a></li>
+</ul>
+</ul></div>
+<div class="panelMacro"><table class="infoMacro"><colgroup><col width="24"><col></colgroup><tbody><tr><td valign="top"><img src="event-admin-handlers_files/information.gif" alt="" border="0" align="absmiddle" height="16" width="16"></td><td><b>change in the 1.2.0</b><br><p>The 1.2.0 version use the namespace : <tt>org.apache.felix.ipojo.handlers.event</tt> instead of <tt>org.apache.felix.ipojo.handlers.event.EventAdminHandler</tt></p></td></tr></tbody></table></div>
+
+<h2><a name="EventAdminHandlers-Anexample"></a>An example</h2>
<p>Hereafter is presented a small example of the metadata.xml file :</p>
-<div class="code"><div class="codeContent">
-<pre class="code-xml"><ipojo
- <span class="code-keyword">xmlns:ev</span>=<span class="code-quote">"org.apache.felix.ipojo.handlers.event.EventAdminHandler"</span>>
- <span class="code-tag"><component className=<span class="code-quote">"...MyComponent"</span>></span>
+<div class="code">
+<div class="dp-highlighter"><table class="dp-xml" border="0" cellpadding="0" cellspacing="0"><tbody><tr><td class="line1"><span></span><span class="tag"><</span><span>ipojo </span></td></tr><tr><td class="line2"> xmlns:<span class="attribute">ev</span><span>=</span><span class="attribute-value">"org.apache.felix.ipojo.handlers.event"</span><span>> </span></td></tr><tr><td class="line1"> <span class="tag"><</span><span>component </span><span class="attribute">className</span><span>=</span><span class="attribute-value">"...MyComponent"</span><span>> </span></td></tr><tr><td class="line2"> <span class="tag"><</span><span>ev:subscriber </span></td></tr><tr><td class="line1"> <span class="attribute">name</span><span>=</span><span class="attribute-value">"mySubscriber"</span><span> </span></td></tr><tr><td class="line2"> <span class="attribute">callback</span><span>=</span><span class="attribute-value">"receive"</span><span> </span></td></tr><tr><td class="line1"> <span class="attribute">topics</span><span>=</span><span class="attribute-value">"foo"</span><span>/> </span></td></tr><tr><td class="line2"> <span class="tag"><</span><span>ev:publisher </span></td></tr><tr><td class="line1"> <span class="attribute">name</span><span>=</span><span class="attribute-value">"myPublisher"</span><span> </span></td></tr><tr><td class="line2"> <span class="attribute">field</span><span>=</span><span class="attribute-value">"m_publisher"</span><span> </span></td></tr><tr><td class="line1"> <span class="attribute">topics</span><span>=</span><span class="attribute-value">"bar,nuts"</span><span>/> </span></td></tr><tr><td class="line2"> <span class="tag"></</span><span>component</span><span class="tag">></span><span> </span></td></tr><tr><td class="line1"> <span class="tag"><</span><span>instance </span><span class="attribute">component</span><span>=</span><span class="attribute-value">"...MyComponent"</span><span>/> </span></td></tr><tr><td class="line2"><span class="tag"></</span><span>ipojo</span><span class="tag">></span><span> </span></td></tr></tbody></table></div><textarea style="display: none;" name="newcodemacro" class="xml:nocontrols:nogutter" rows="10" readonly="readonly"><ipojo
+ xmlns:ev="org.apache.felix.ipojo.handlers.event">
+ <component className="...MyComponent">
<ev:subscriber
- name=<span class="code-quote">"mySubscriber"</span>
- callback=<span class="code-quote">"receive"</span>
- topics=<span class="code-quote">"foo"</span>/>
+ name="mySubscriber"
+ callback="receive"
+ topics="foo"/>
<ev:publisher
- name=<span class="code-quote">"myPublisher"</span>
- field=<span class="code-quote">"m_publisher"</span>
- topics=<span class="code-quote">"bar,nuts"</span>/>
- <span class="code-tag"></component></span>
- <span class="code-tag"><instance component=<span class="code-quote">"...MyComponent"</span>/></span>
-<span class="code-tag"></ipojo></span></pre>
-</div></div>
+ name="myPublisher"
+ field="m_publisher"
+ topics="bar,nuts"/>
+ </component>
+ <instance component="...MyComponent"/>
+</ipojo></textarea>
+<script class="javascript">
+ if(!window.newcodemacro_initialised)
+ {
+ window.newcodemacro_initialised = true;
+ window.oldonloadmethod = window.onload;
+ window.onload = function(){
+ dp.SyntaxHighlighter.HighlightAll('newcodemacro');
+ if(window.oldonloadmethod)
+ {
+ window.oldonloadmethod();
+ }
+ }
+ }
+
+</script>
+</div>
+
<p>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
@@ -69,32 +263,48 @@
will be checked by the handler at component instantiation time.</p>
<p>Here is an example of the component implementation, compatible with the given description :</p>
-<div class="code"><div class="codeContent">
-<pre class="code-java"><span class="code-keyword">import</span> org.apache.felix.ipojo.handlers.event.publisher.Publisher;
-<span class="code-keyword">import</span> org.osgi.service.event.Event;
+<div class="code">
+<div class="dp-highlighter"><table class="dp-c" border="0" cellpadding="0" cellspacing="0"><tbody><tr><td class="line1"><span></span><span class="keyword">import</span><span> org.apache.felix.ipojo.handlers.event.publisher.Publisher; </span></td></tr><tr><td class="line2"><span class="keyword">import</span><span> org.osgi.service.event.Event; </span></td></tr><tr><td class="line1"> </td></tr><tr><td class="line2"><span class="keyword">public</span><span> </span><span class="keyword">class</span><span> MyComponent ... { </span></td></tr><tr><td class="line1"> <span class="keyword">private</span><span> Publisher m_publisher; </span></td></tr><tr><td class="line2"> <span class="keyword">public</span><span> </span><span class="keyword">void</span><span> receive(Event e) { </span></td></tr><tr><td class="line1"> <span class="comment">// Event received</span><span> </span></td></tr><tr><td class="line2"> <span class="comment">// Do something with the event}</span><span> </span></td></tr><tr><td class="line1"> </td></tr><tr><td class="line2"> <span class="keyword">public</span><span> </span><span class="keyword">void</span><span> doSomething() { </span></td></tr><tr><td class="line1"> Dictionary e = new Properties(); </td></tr><tr><td class="line2"> <span class="comment">//...</span><span> </span></td></tr><tr><td class="line1"> <span class="comment">// Fill out the event</span><span> </span></td></tr><tr><td class="line2"> </td></tr><tr><td class="line1"> <span class="comment">// Send event</span><span> </span></td></tr><tr><td class="line2"> m_publisher.send(e); </td></tr><tr><td class="line1"> } </td></tr><tr><td class="line2">} </td></tr></tbody></table></div><textarea style="display: none;" name="newcodemacro" class="java:nocontrols:nogutter" rows="10" readonly="readonly">import org.apache.felix.ipojo.handlers.event.publisher.Publisher;
+import org.osgi.service.event.Event;
-<span class="code-keyword">public</span> class MyComponent ... {
- <span class="code-keyword">private</span> Publisher m_publisher;
- <span class="code-keyword">public</span> void receive(Event e) {
- <span class="code-comment">// Event received
-</span> <span class="code-comment">// Do something with the event}
-</span>
- <span class="code-keyword">public</span> void doSomething() {
- Dictionary e = <span class="code-keyword">new</span> Properties();
- <span class="code-comment">//...
-</span> <span class="code-comment">// Fill out the event
-</span>
- <span class="code-comment">// Send event
-</span> m_publisher.send(e);
+public class MyComponent ... {
+ private Publisher m_publisher;
+ public void receive(Event e) {
+ // Event received
+ // Do something with the event}
+
+ public void doSomething() {
+ Dictionary e = new Properties();
+ //...
+ // Fill out the event
+
+ // Send event
+ m_publisher.send(e);
}
-}</pre>
-</div></div>
+}</textarea>
+<script class="javascript">
+ if(!window.newcodemacro_initialised)
+ {
+ window.newcodemacro_initialised = true;
+ window.oldonloadmethod = window.onload;
+ window.onload = function(){
+ dp.SyntaxHighlighter.HighlightAll('newcodemacro');
+ if(window.oldonloadmethod)
+ {
+ window.oldonloadmethod();
+ }
+ }
+ }
-<h1><a name="EventAdminHandlers-Download"></a>Download</h1>
+</script>
+</div>
+
+
+<h2><a name="EventAdminHandlers-Download"></a>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="http://felix.apache.org/site/download.html" title="Download">Download</a> page to download and compile these sources.</p>
-<h1><a name="EventAdminHandlers-Howdoesitwork?"></a>How does it work?</h1>
+<h2><a name="EventAdminHandlers-Howdoesitwork?"></a>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,
@@ -104,7 +314,7 @@
configured Publisher references in your POJO, so you can send events
transparently through these publishers.</p>
-<h1><a name="EventAdminHandlers-EventHandlerSpecification"></a>EventHandler Specification</h1>
+<h2><a name="EventAdminHandlers-EventHandlerSpecification"></a>EventHandler Specification</h2>
<p>Here you can find all configuration options of the EventAdmin
handler. As seen before, the handler contains two components : the
@@ -112,11 +322,10 @@
configured, using several attributes, as described below. Some of these
attributes can be (re)defined in the instance configuration.</p>
-<p>Handler namespace : org.apache.felix.ipojo.handlers.event.EventAdminHandler</p>
+<p><b>Handler namespace :</b> org.apache.felix.ipojo.handlers.event</p>
-<h2><a name="EventAdminHandlers-Eventsubscriberattributes"></a>Event subscriber attributes</h2>
-
-<table class="confluenceTable"><tbody>
+<h3><a name="EventAdminHandlers-Eventsubscriberattributes"></a>Event subscriber attributes</h3>
+<div class="borderedTable"><table class="confluenceTable"><tbody>
<tr>
<th class="confluenceTh"> Attribute name </th>
<th class="confluenceTh"> Required </th>
@@ -173,11 +382,9 @@
filter, all events sent on the listened topics will be considered. </td>
</tr>
</tbody></table>
-<p>* These attributes can be (re)defined in the instance configuration.</p>
-
-<h2><a name="EventAdminHandlers-Eventpublisherattributes"></a>Event publisher attributes</h2>
-
-<table class="confluenceTable"><tbody>
+<p>* These attributes can be (re)defined in the instance configuration.</p></div>
+<h3><a name="EventAdminHandlers-Eventpublisherattributes"></a>Event publisher attributes</h3>
+<div class="borderedTable"><table class="confluenceTable"><tbody>
<tr>
<th class="confluenceTh"> Attribute name </th>
<th class="confluenceTh"> Required </th>
@@ -220,9 +427,8 @@
The default value of this attribute is "false". </td>
</tr>
</tbody></table>
-<p>* These attributes can be (re)defined in the instance configuration.</p>
-
-<h2><a name="EventAdminHandlers-Instanceconfiguration"></a>Instance configuration</h2>
+<p>* These attributes can be (re)defined in the instance configuration.</p></div>
+<h3><a name="EventAdminHandlers-Instanceconfiguration"></a>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
@@ -234,7 +440,7 @@
</ul>
-<h2><a name="EventAdminHandlers-Publisherinterface"></a>Publisher interface</h2>
+<h3><a name="EventAdminHandlers-Publisherinterface"></a>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
@@ -250,51 +456,64 @@
</ul>
-<h1><a name="EventAdminHandlers-HandlerArchitecture"></a>Handler Architecture</h1>
+<h2><a name="EventAdminHandlers-HandlerArchitecture"></a>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><img src="event-admin-handlers_files/handler-arch.png" align="absmiddle" border="0"></p>
+<p><img src="event-admin-handlers_files/handler-arch.png" border="0" align="absmiddle"></p>
-<h1><a name="EventAdminHandlers-EventHandlerFeatures"></a>EventHandler Features</h1>
-
+<h2><a name="EventAdminHandlers-EventHandlerFeatures"></a>EventHandler Features</h2>
<p>In this section, you will find some examples of the handler's features.</p>
-<h2><a name="EventAdminHandlers-Instancecustomization"></a>Instance customization</h2>
-
+<h3><a name="EventAdminHandlers-Instancecustomization"></a>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="code"><div class="codeContent">
-<pre class="code-xml"><ipojo
- <span class="code-keyword">xmlns:ev</span>=<span class="code-quote">"org.apache.felix.ipojo.handlers.event.EventAdminHandler"</span>>
- <span class="code-tag"><component className=<span class="code-quote">"...MyComponent"</span>></span>
+<div class="code">
+<div class="dp-highlighter"><table class="dp-xml" border="0" cellpadding="0" cellspacing="0"><tbody><tr><td class="line1"><span></span><span class="tag"><</span><span>ipojo </span></td></tr><tr><td class="line2"> xmlns:<span class="attribute">ev</span><span>=</span><span class="attribute-value">"org.apache.felix.ipojo.handlers.event"</span><span>> </span></td></tr><tr><td class="line1"> <span class="tag"><</span><span>component </span><span class="attribute">className</span><span>=</span><span class="attribute-value">"...MyComponent"</span><span>> </span></td></tr><tr><td class="line2"> <span class="tag"><</span><span>ev:subscriber </span></td></tr><tr><td class="line1"> <span class="attribute">name</span><span>=</span><span class="attribute-value">"mySubscriber"</span><span> </span></td></tr><tr><td class="line2"> <span class="attribute">callback</span><span>=</span><span class="attribute-value">"handleEvent"</span><span>/> </span></td></tr><tr><td class="line1"> <span class="tag"><</span><span>ev:publisher </span></td></tr><tr><td class="line2"> <span class="attribute">name</span><span>=</span><span class="attribute-value">"myPublisher"</span><span> </span></td></tr><tr><td class="line1"> <span class="attribute">field</span><span>=</span><span class="attribute-value">"m_publisher"</span><span>/> </span></td></tr><tr><td class="line2"> <span class="tag"></</span><span>component</span><span class="tag">></span><span> </span></td></tr><tr><td class="line1"> <span class="tag"><</span><span>instance </span><span class="attribute">component</span><span>=</span><span class="attribute-value">"...MyComponent"</span><span>> </span></td></tr><tr><td class="line2"> <span class="tag"><</span><span>property </span><span class="attribute">name</span><span>=</span><span class="attribute-value">"event.topics"</span><span>> </span></td></tr><tr><td class="line1"> <span class="tag"><</span><span>property </span><span class="attribute">name</span><span>=</span><span class="attribute-value">"mySubscriber"</span><span> </span><span class="attribute">value</span><span>=</span><span class="attribute-value">"foo"</span><span>/> </span></td></tr><tr><td class="line2"> <span class="tag"><</span><span>property </span><span class="attribute">name</span><span>=</span><span class="attribute-value">"myPublisher"</span><span> </span><span class="attribute">value</span><span>=</span><span class="attribute-value">"bar,nuts"</span><span>/> </span></td></tr><tr><td class="line1"> <span class="tag"></</span><span>property</span><span class="tag">></span><span> </span></td></tr><tr><td class="line2"> <span class="tag"><</span><span>property </span><span class="attribute">name</span><span>=</span><span class="attribute-value">"event.filter"</span><span>> </span></td></tr><tr><td class="line1"> <span class="tag"><</span><span>property </span><span class="attribute">name</span><span>=</span><span class="attribute-value">"mySubscriber"</span><span> </span></td></tr><tr><td class="line2"> <span class="attribute">value</span><span>=</span><span class="attribute-value">"|((arg=Minibar)(arg=Coconuts))"</span><span>/> </span></td></tr><tr><td class="line1"> <span class="tag"></</span><span>property</span><span class="tag">></span><span> </span></td></tr><tr><td class="line2"> <span class="tag"></</span><span>instance</span><span class="tag">></span><span> </span></td></tr><tr><td class="line1"><span class="tag"></</span><span>ipojo</span><span class="tag">></span><span> </span></td></tr></tbody></table></div><textarea style="display: none;" name="newcodemacro" class="xml:nocontrols:nogutter" rows="10" readonly="readonly"><ipojo
+ xmlns:ev="org.apache.felix.ipojo.handlers.event">
+ <component className="...MyComponent">
<ev:subscriber
- name=<span class="code-quote">"mySubscriber"</span>
- callback=<span class="code-quote">"handleEvent"</span>/>
+ name="mySubscriber"
+ callback="handleEvent"/>
<ev:publisher
- name=<span class="code-quote">"myPublisher"</span>
- field=<span class="code-quote">"m_publisher"</span>/>
- <span class="code-tag"></component></span>
- <span class="code-tag"><instance component=<span class="code-quote">"...MyComponent"</span>></span>
- <span class="code-tag"><property name=<span class="code-quote">"event.topics"</span>></span>
- <span class="code-tag"><property name=<span class="code-quote">"mySubscriber"</span> value=<span class="code-quote">"foo"</span>/></span>
- <span class="code-tag"><property name=<span class="code-quote">"myPublisher"</span> value=<span class="code-quote">"bar,nuts"</span>/></span>
- <span class="code-tag"></property></span>
- <span class="code-tag"><property name=<span class="code-quote">"event.filter"</span>></span>
- <property name=<span class="code-quote">"mySubscriber"</span>
- value=<span class="code-quote">"|((arg=Minibar)(arg=Coconuts))"</span>/>
- <span class="code-tag"></property></span>
- <span class="code-tag"></instance></span>
-<span class="code-tag"></ipojo></span></pre>
-</div></div>
+ name="myPublisher"
+ field="m_publisher"/>
+ </component>
+ <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></textarea>
+<script class="javascript">
+ if(!window.newcodemacro_initialised)
+ {
+ window.newcodemacro_initialised = true;
+ window.oldonloadmethod = window.onload;
+ window.onload = function(){
+ dp.SyntaxHighlighter.HighlightAll('newcodemacro');
+ if(window.oldonloadmethod)
+ {
+ window.oldonloadmethod();
+ }
+ }
+ }
-<h2><a name="EventAdminHandlers-Dataevents"></a>Data events</h2>
+</script>
+</div>
+
+<h3><a name="EventAdminHandlers-Dataevents"></a>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
@@ -305,67 +524,131 @@
<p>First, you have define the <em>data-key</em> attribute in the
publisher configuration. Sent objects will be contained in the event
dictionary and are accessible with the "user.data" key.</p>
-<div class="code"><div class="codeContent">
-<pre class="code-xml"><ipojo
- <span class="code-keyword">xmlns:ev</span>=<span class="code-quote">"org.apache.felix.ipojo.handlers.event.EventAdminHandler"</span>>
- <span class="code-tag"><component className=<span class="code-quote">"...DataPublisher"</span>></span>
+<div class="code">
+<div class="dp-highlighter"><table class="dp-xml" border="0" cellpadding="0" cellspacing="0"><tbody><tr><td class="line1"><span></span><span class="tag"><</span><span>ipojo </span></td></tr><tr><td class="line2"> xmlns:<span class="attribute">ev</span><span>=</span><span class="attribute-value">"org.apache.felix.ipojo.handlers.event"</span><span>> </span></td></tr><tr><td class="line1"> <span class="tag"><</span><span>component </span><span class="attribute">className</span><span>=</span><span class="attribute-value">"...DataPublisher"</span><span>> </span></td></tr><tr><td class="line2"> <span class="tag"><</span><span>ev:publisher </span></td></tr><tr><td class="line1"> <span class="attribute">name</span><span>=</span><span class="attribute-value">"myPublisher"</span><span> </span></td></tr><tr><td class="line2"> <span class="attribute">field</span><span>=</span><span class="attribute-value">"m_publisher"</span><span> </span></td></tr><tr><td class="line1"> <span class="attribute">topics</span><span>=</span><span class="attribute-value">"myTopic"</span><span> </span></td></tr><tr><td class="line2"> <span class="attribute">data-key</span><span>=</span><span class="attribute-value">"my.data"</span><span>/> </span></td></tr><tr><td class="line1"> <span class="tag"></</span><span>component</span><span class="tag">></span><span> </span></td></tr><tr><td class="line2"> <span class="tag"><</span><span>instance </span><span class="attribute">component</span><span>=</span><span class="attribute-value">"...DataPublisher"</span><span>/> </span></td></tr><tr><td class="line1"><span class="tag"></</span><span>ipojo</span><span class="tag">></span><span> </span></td></tr></tbody></table></div><textarea style="display: none;" name="newcodemacro" class="xml:nocontrols:nogutter" rows="10" readonly="readonly"><ipojo
+ xmlns:ev="org.apache.felix.ipojo.handlers.event">
+ <component className="...DataPublisher">
<ev:publisher
- name=<span class="code-quote">"myPublisher"</span>
- field=<span class="code-quote">"m_publisher"</span>
- topics=<span class="code-quote">"myTopic"</span>
- data-key=<span class="code-quote">"my.data"</span>/>
- <span class="code-tag"></component></span>
- <span class="code-tag"><instance component=<span class="code-quote">"...DataPublisher"</span>/></span>
-<span class="code-tag"></ipojo></span></pre>
-</div></div>
-<p>Then you can use the <em>sendData</em> method of your configured publisher.</p>
-<div class="code"><div class="codeContent">
-<pre class="code-java"><span class="code-keyword">import</span> org.apache.felix.ipojo.handlers.event.publisher.Publisher;
-<span class="code-comment">//...
-</span><span class="code-keyword">public</span> class DataPublisher ... {
- <span class="code-keyword">private</span> Publisher m_publisher;
-
- <span class="code-keyword">public</span> void doSomething() {
- <span class="code-comment">// MyFavoriteType <span class="code-keyword">extends</span> MyFavoriteInterface
-</span> MyFavoriteType data = <span class="code-keyword">new</span> MyFavoriteType(...);
- <span class="code-comment">//...
-</span> <span class="code-comment">// Send a data event
-</span> m_publisher.sendData(data);
+ name="myPublisher"
+ field="m_publisher"
+ topics="myTopic"
+ data-key="my.data"/>
+ </component>
+ <instance component="...DataPublisher"/>
+</ipojo></textarea>
+<script class="javascript">
+ if(!window.newcodemacro_initialised)
+ {
+ window.newcodemacro_initialised = true;
+ window.oldonloadmethod = window.onload;
+ window.onload = function(){
+ dp.SyntaxHighlighter.HighlightAll('newcodemacro');
+ if(window.oldonloadmethod)
+ {
+ window.oldonloadmethod();
+ }
+ }
}
-}</pre>
-</div></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>describe
-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="code"><div class="codeContent">
-<pre class="code-xml"><ipojo
- <span class="code-keyword">xmlns:ev</span>=<span class="code-quote">"org.apache.felix.ipojo.handlers.event.EventAdminHandler"</span>>
- <span class="code-tag"><component className=<span class="code-quote">"...DataEventSubscriber"</span>></span>
- <ev:subscriber
- name=<span class="code-quote">"mySubscriber"</span>
- callback=<span class="code-quote">"handleData"</span>
- topics=<span class="code-quote">"myTopic"</span>
- data-key=<span class="code-quote">"my.data"</span>
- data-type=<span class="code-quote">"my.package.MyFavoriteInterface"</span>/>
- <span class="code-tag"></component></span>
- <span class="code-tag"><instance component=<span class="code-quote">"...DataEventSubscriber"</span>/></span>
-<span class="code-tag"></ipojo></span></pre>
-</div></div>
-<div class="code"><div class="codeContent">
-<pre class="code-java"><span class="code-keyword">import</span> my.<span class="code-keyword">package</span>.MyFavoriteInterface;
-<span class="code-comment">//...
-</span><span class="code-keyword">public</span> class DataEventSubscriber ... {
- <span class="code-keyword">public</span> void handleData(MyFavoriteInterface o) {
- <span class="code-comment">// <span class="code-object">Object</span> received
-</span> <span class="code-comment">//...
-</span> }
-}</pre>
-</div></div>
-<h2><a name="EventAdminHandlers-Noteonsynchronouseventsending"></a>Note on synchronous event sending</h2>
+</script>
+</div>
+
+<p>Then you can use the <em>sendData</em> method of your configured publisher.</p>
+<div class="code">
+<div class="dp-highlighter"><table class="dp-c" border="0" cellpadding="0" cellspacing="0"><tbody><tr><td class="line1"><span></span><span class="keyword">import</span><span> org.apache.felix.ipojo.handlers.event.publisher.Publisher; </span></td></tr><tr><td class="line2"><span class="comment">//...</span><span> </span></td></tr><tr><td class="line1"><span class="keyword">public</span><span> </span><span class="keyword">class</span><span> DataPublisher ... { </span></td></tr><tr><td class="line2"> <span class="keyword">private</span><span> Publisher m_publisher; </span></td></tr><tr><td class="line1"> </td></tr><tr><td class="line2"> <span class="keyword">public</span><span> </span><span class="keyword">void</span><span> doSomething() { </span></td></tr><tr><td class="line1"> <span class="comment">// MyFavoriteType extends MyFavoriteInterface</span><span> </span></td></tr><tr><td class="line2"> MyFavoriteType data = new MyFavoriteType(...); </td></tr><tr><td class="line1"> <span class="comment">//...</span><span> </span></td></tr><tr><td class="line2"> <span class="comment">// Send a data event</span><span> </span></td></tr><tr><td class="line1"> m_publisher.sendData(data); </td></tr><tr><td class="line2"> } </td></tr><tr><td class="line1">} </td></tr></tbody></table></div><textarea style="display: none;" name="newcodemacro" class="java:nocontrols:nogutter" rows="10" readonly="readonly">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);
+ }
+}</textarea>
+<script class="javascript">
+ if(!window.newcodemacro_initialised)
+ {
+ window.newcodemacro_initialised = true;
+ window.oldonloadmethod = window.onload;
+ window.onload = function(){
+ dp.SyntaxHighlighter.HighlightAll('newcodemacro');
+ if(window.oldonloadmethod)
+ {
+ window.oldonloadmethod();
+ }
+ }
+ }
+
+</script>
+</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="code">
+<div class="dp-highlighter"><table class="dp-xml" border="0" cellpadding="0" cellspacing="0"><tbody><tr><td class="line1"><span></span><span class="tag"><</span><span>ipojo </span></td></tr><tr><td class="line2"> xmlns:<span class="attribute">ev</span><span>=</span><span class="attribute-value">"org.apache.felix.ipojo.handlers.event"</span><span>> </span></td></tr><tr><td class="line1"> <span class="tag"><</span><span>component </span><span class="attribute">className</span><span>=</span><span class="attribute-value">"...DataEventSubscriber"</span><span>> </span></td></tr><tr><td class="line2"> <span class="tag"><</span><span>ev:subscriber </span></td></tr><tr><td class="line1"> <span class="attribute">name</span><span>=</span><span class="attribute-value">"mySubscriber"</span><span> </span></td></tr><tr><td class="line2"> <span class="attribute">callback</span><span>=</span><span class="attribute-value">"handleData"</span><span> </span></td></tr><tr><td class="line1"> <span class="attribute">topics</span><span>=</span><span class="attribute-value">"myTopic"</span><span> </span></td></tr><tr><td class="line2"> <span class="attribute">data-key</span><span>=</span><span class="attribute-value">"my.data"</span><span> </span></td></tr><tr><td class="line1"> <span class="attribute">data-type</span><span>=</span><span class="attribute-value">"my.package.MyFavoriteInterface"</span><span>/> </span></td></tr><tr><td class="line2"> <span class="tag"></</span><span>component</span><span class="tag">></span><span> </span></td></tr><tr><td class="line1"> <span class="tag"><</span><span>instance </span><span class="attribute">component</span><span>=</span><span class="attribute-value">"...DataEventSubscriber"</span><span>/> </span></td></tr><tr><td class="line2"><span class="tag"></</span><span>ipojo</span><span class="tag">></span><span> </span></td></tr></tbody></table></div><textarea style="display: none;" name="newcodemacro" class="xml:nocontrols:nogutter" rows="10" readonly="readonly"><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></textarea>
+<script class="javascript">
+ if(!window.newcodemacro_initialised)
+ {
+ window.newcodemacro_initialised = true;
+ window.oldonloadmethod = window.onload;
+ window.onload = function(){
+ dp.SyntaxHighlighter.HighlightAll('newcodemacro');
+ if(window.oldonloadmethod)
+ {
+ window.oldonloadmethod();
+ }
+ }
+ }
+
+</script>
+</div>
+
+<div class="code">
+<div class="dp-highlighter"><table class="dp-c" border="0" cellpadding="0" cellspacing="0"><tbody><tr><td class="line1"><span></span><span class="keyword">import</span><span> my.</span><span class="keyword">package</span><span>.MyFavoriteInterface; </span></td></tr><tr><td class="line2"><span class="comment">//...</span><span> </span></td></tr><tr><td class="line1"><span class="keyword">public</span><span> </span><span class="keyword">class</span><span> DataEventSubscriber ... { </span></td></tr><tr><td class="line2"> <span class="keyword">public</span><span> </span><span class="keyword">void</span><span> handleData(MyFavoriteInterface o) { </span></td></tr><tr><td class="line1"> <span class="comment">// Object received</span><span> </span></td></tr><tr><td class="line2"> <span class="comment">//...</span><span> </span></td></tr><tr><td class="line1"> } </td></tr><tr><td class="line2">} </td></tr></tbody></table></div><textarea style="display: none;" name="newcodemacro" class="java:nocontrols:nogutter" rows="10" readonly="readonly">import my.package.MyFavoriteInterface;
+//...
+public class DataEventSubscriber ... {
+ public void handleData(MyFavoriteInterface o) {
+ // Object received
+ //...
+ }
+}</textarea>
+<script class="javascript">
+ if(!window.newcodemacro_initialised)
+ {
+ window.newcodemacro_initialised = true;
+ window.oldonloadmethod = window.onload;
+ window.onload = function(){
+ dp.SyntaxHighlighter.HighlightAll('newcodemacro');
+ if(window.oldonloadmethod)
+ {
+ window.oldonloadmethod();
+ }
+ }
+ }
+
+</script>
+</div>
+
+
+<h3><a name="EventAdminHandlers-Noteonsynchronouseventsending"></a>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>
@@ -375,7 +658,7 @@
this function, you can be sure that the event has been delivered to
each topic.</p>
-<h2><a name="EventAdminHandlers-Publisherinstanceinformation"></a>Publisher instance information</h2>
+<h3><a name="EventAdminHandlers-Publisherinstanceinformation"></a>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
@@ -383,120 +666,77 @@
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>
-<h2><a name="EventAdminHandlers-Configuringthehandlerwithannotations\Newin1.1.0SNAPSHOT\"></a>Configuring the handler with annotations [New in 1.1.0-SNAPSHOT]</h2>
+<h3><a name="EventAdminHandlers-Configuringthehandlerwithannotations"></a>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:</p>
-<div class="code"><div class="codeContent">
-<pre class="code-java"><span class="code-keyword">import</span> org.apache.felix.ipojo.annotations.Component;
-<span class="code-keyword">import</span> org.apache.felix.ipojo.handlers.event.Subscriber;
-<span class="code-keyword">import</span> org.osgi.service.event.Event;
+<div class="code">
+<div class="dp-highlighter"><table class="dp-c" border="0" cellpadding="0" cellspacing="0"><tbody><tr><td class="line1"><span></span><span class="keyword">import</span><span> org.apache.felix.ipojo.annotations.Component; </span></td></tr><tr><td class="line2"><span class="keyword">import</span><span> org.apache.felix.ipojo.handlers.event.Subscriber; </span></td></tr><tr><td class="line1"><span class="keyword">import</span><span> org.osgi.service.event.Event; </span></td></tr><tr><td class="line2"><span class="preprocessor"></span></td></tr><tr><td class="line1"><span class="preprocessor"></span></td></tr><tr><td class="line2"><span class="preprocessor">@Component</span><span> </span></td></tr><tr><td class="line1"><span class="keyword">public</span><span> </span><span class="keyword">class</span><span> PubSub { </span></td></tr><tr><td class="line2"><span class="preprocessor"> @org.apache.felix.ipojo.handlers.event.Publisher(name="p1", synchronous=true)</span><span> </span></td></tr><tr><td class="line1"> org.apache.felix.ipojo.handlers.event.publisher.Publisher publisher1; </td></tr><tr><td class="line2"><span class="preprocessor"> </span></td></tr><tr><td class="line1"><span class="preprocessor"> @org.apache.felix.ipojo.handlers.event.Publisher(name="p2", synchronous=false, topics="foo,bar", data_key="data")</span><span> </span></td></tr><tr><td class="line2"> org.apache.felix.ipojo.handlers.event.publisher.Publisher publisher2; </td></tr><tr><td class="line1"><span class="preprocessor"> </span></td></tr><tr><td class="line2"><span class="preprocessor"> @org.apache.felix.ipojo.handlers.event.Publisher(name="p3", synchronous=true, topics="bar")</span><span> </span></td></tr><tr><td class="line1"> org.apache.felix.ipojo.handlers.event.publisher.Publisher publisher3; </td></tr><tr><td class="line2"><span class="preprocessor"> </span></td></tr><tr><td class="line1"><span class="preprocessor"> @Subscriber(name="s1", data_key="data")</span><span> </span></td></tr><tr><td class="line2"> <span class="keyword">public</span><span> </span><span class="keyword">void</span><span> receive1(Object foo) { </span></td></tr><tr><td class="line1"> <span class="comment">// Process event</span><span> </span></td></tr><tr><td class="line2"> } </td></tr><tr><td class="line1"><span class="preprocessor"> </span></td></tr><tr><td class="line2"><span class="preprocessor"> @Subscriber(name="s2", topics="foo,bar", filter="(foo=true)")</span><span> </span></td></tr><tr><td class="line1"> <span class="keyword">public</span><span> </span><span class="keyword">void</span><span> receive2(Event foo) { </span></td></tr><tr><td class="line2"> <span class="comment">// Process event</span><span> </span></td></tr><tr><td class="line1"> } </td></tr><tr><td class="line2"><span class="preprocessor"> </span></td></tr><tr><td class="line1"><span class="preprocessor"> </span></td></tr><tr><td class="line2"><span class="preprocessor"> @Subscriber(name="s3", topics="foo", data_key="data", data_type="java.lang.String")</span><span> </span></td></tr><tr><td class="line1"> <span class="keyword">public</span><span> </span><span class="keyword">void</span><span> receive3(String foo) { </span></td></tr><tr><td class="line2"> <span class="comment">// Process event</span><span> </span></td></tr><tr><td class="line1"> } </td></tr><tr><td class="line2">} </td></tr></tbody></table></div><textarea style="display: none;" name="newcodemacro" class="java:nocontrols:nogutter" rows="10" readonly="readonly">import org.apache.felix.ipojo.annotations.Component;
+import org.apache.felix.ipojo.handlers.event.Subscriber;
+import org.osgi.service.event.Event;
@Component
-<span class="code-keyword">public</span> class PubSub {
- @org.apache.felix.ipojo.handlers.event.Publisher(name=<span class="code-quote">"p1"</span>, synchronous=<span class="code-keyword">true</span>)
+public class PubSub {
+ @org.apache.felix.ipojo.handlers.event.Publisher(name="p1", synchronous=true)
org.apache.felix.ipojo.handlers.event.publisher.Publisher publisher1;
- @org.apache.felix.ipojo.handlers.event.Publisher(name=<span class="code-quote">"p2"</span>, synchronous=<span class="code-keyword">false</span>, topics=<span class="code-quote">"foo,bar"</span>, data_key=<span class="code-quote">"data"</span>)
+ @org.apache.felix.ipojo.handlers.event.Publisher(name="p2", synchronous=false, topics="foo,bar", data_key="data")
org.apache.felix.ipojo.handlers.event.publisher.Publisher publisher2;
- @org.apache.felix.ipojo.handlers.event.Publisher(name=<span class="code-quote">"p3"</span>, synchronous=<span class="code-keyword">true</span>, topics=<span class="code-quote">"bar"</span>)
+ @org.apache.felix.ipojo.handlers.event.Publisher(name="p3", synchronous=true, topics="bar")
org.apache.felix.ipojo.handlers.event.publisher.Publisher publisher3;
- @Subscriber(name=<span class="code-quote">"s1"</span>, data_key=<span class="code-quote">"data"</span>)
- <span class="code-keyword">public</span> void receive1(<span class="code-object">Object</span> foo) {
- <span class="code-comment">// <span class="code-object">Process</span> event
-</span> }
+ @Subscriber(name="s1", data_key="data")
+ public void receive1(Object foo) {
+ // Process event
+ }
- @Subscriber(name=<span class="code-quote">"s2"</span>, topics=<span class="code-quote">"foo,bar"</span>, filter=<span class="code-quote">"(foo=<span class="code-keyword">true</span>)"</span>)
- <span class="code-keyword">public</span> void receive2(Event foo) {
- <span class="code-comment">// <span class="code-object">Process</span> event
-</span> }
+ @Subscriber(name="s2", topics="foo,bar", filter="(foo=true)")
+ public void receive2(Event foo) {
+ // Process event
+ }
- @Subscriber(name=<span class="code-quote">"s3"</span>, topics=<span class="code-quote">"foo"</span>, data_key=<span class="code-quote">"data"</span>, data_type=<span class="code-quote">"java.lang.<span class="code-object">String</span>"</span>)
- <span class="code-keyword">public</span> void receive3(<span class="code-object">String</span> foo) {
- <span class="code-comment">// <span class="code-object">Process</span> event
-</span> }
-}</pre>
-</div></div></td>
-<td class="confluenceTd" valign="top" width="20%">
-<h6><a name="EventAdminHandlers-Overview"></a><b>Overview</b></h6>
-<ul>
- <li><a href="http://felix.apache.org/site/apache-felix-ipojo.html" title="Apache Felix iPOJO">Home Page</a></li>
- <li><a href="http://felix.apache.org/site/apache-felix-ipojo-feature-overview.html" title="Apache Felix iPOJO Feature Overview">iPOJO Feature Overview</a></li>
- <li><a href="http://felix.apache.org/site/download.html" title="Download">Download & Install </a></li>
-</ul>
+ @Subscriber(name="s3", topics="foo", data_key="data", data_type="java.lang.String")
+ public void receive3(String foo) {
+ // Process event
+ }
+}</textarea>
+<script class="javascript">
+ if(!window.newcodemacro_initialised)
+ {
+ window.newcodemacro_initialised = true;
+ window.oldonloadmethod = window.onload;
+ window.onload = function(){
+ dp.SyntaxHighlighter.HighlightAll('newcodemacro');
+ if(window.oldonloadmethod)
+ {
+ window.oldonloadmethod();
+ }
+ }
+ }
+</script>
+</div>
-<h6><a name="EventAdminHandlers-GettingStarted"></a><b>Getting Started</b></h6>
-<ul>
- <li><a href="http://felix.apache.org/site/ipojo-in-10-minutes.html" title="iPOJO in 10 minutes">iPOJO in 10 minutes</a></li>
- <li><a href="http://felix.apache.org/site/how-to-use-ipojo-annotations.html" title="How to use iPOJO Annotations">How to use iPOJO Annotations</a></li>
- <li><a href="http://felix.apache.org/site/ipojo-hello-word-maven-based-tutorial.html" title="iPOJO Hello Word (Maven-Based) tutorial">iPOJO Hello Word (Maven-Based) tutorial</a></li>
- <li><a href="http://felix.apache.org/site/ipojo-advanced-tutorial.html" title="iPOJO Advanced Tutorial">iPOJO Advanced Tutorial</a></li>
- <li><a href="http://felix.apache.org/site/ipojo-composition-tutorial.html" title="iPOJO Composition Tutorial">iPOJO Composition Tutorial</a></li>
-</ul>
+<p><br clear="all"></p>
-
-<h6><a name="EventAdminHandlers-UserGuide"></a><b>User Guide</b></h6>
-<ul>
- <li><a href="http://felix.apache.org/site/describing-components.html" title="Describing components">Describing components (handler list) </a></li>
- <li><a href="http://felix.apache.org/site/using-xml-schemas.html" title="Using XML Schemas">Using XML Schemas</a></li>
- <li><a href="http://felix.apache.org/site/apache-felix-ipojo-testing-components.html" title="apache-felix-ipojo-testing-components">Testing components</a></li>
- <li><a href="http://felix.apache.org/site/ipojo-advanced-topics.html" title="iPOJO Advanced Topics">Advanced Topics</a></li>
- <li><a href="http://felix.apache.org/site/ipojo-faq.html" title="iPOJO FAQ">FAQ</a></li>
- <li><a href="http://felix.apache.org/site/ipojo-reference-card.html" title="iPOJO-Reference-Card">iPOJO Reference Card</a></li>
-</ul>
-
-
-<h6><a name="EventAdminHandlers-Tools"></a><b>Tools</b></h6>
-<ul>
- <li><a href="http://felix.apache.org/site/ipojo-eclipse-plug-in.html" title="iPOJO Eclipse Plug-in">iPOJO Eclipse Plug-in</a></li>
- <li><a href="http://felix.apache.org/site/ipojo-ant-task.html" title="iPOJO Ant Task">iPOJO Ant Task</a></li>
- <li><a href="http://felix.apache.org/site/ipojo-maven-plug-in.html" title="iPOJO Maven Plug-in">iPOJO Maven Plug-in</a></li>
- <li><a href="http://felix.apache.org/site/ipojo-arch-command.html" title="iPOJO-Arch-Command">iPOJO Arch Command</a></li>
- <li><a href="http://felix.apache.org/site/apache-felix-ipojo-junit4osgi.html" title="apache-felix-ipojo-junit4osgi">Junit4OSGi</a></li>
- <li><a href="http://felix.apache.org/site/ipojo-concepts-overview.html" title="iPOJO Concepts Overview">iPOJO concepts overview</a></li>
-</ul>
-
-
-<h6><a name="EventAdminHandlers-DeveloperGuide"></a><b>Developer Guide</b></h6>
-<ul>
- <li>API: <span class="nobr"><a href="http://people.apache.org/%7Eclement/ipojo/api/1.0/" title="Visit page outside Confluence" rel="nofollow">1.0<sup><img class="rendericon" src="event-admin-handlers_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
- <li><a href="http://felix.apache.org/site/how-to-write-your-own-handler.html" title="How to write your own handler">How to write your own handler</a></li>
- <li><a href="http://felix.apache.org/site/how-to-use-ipojo-manipulation-metadata.html" title="How to use iPOJO Manipulation Metadata">How to use iPOJO Manipulation Metadata</a></li>
- <li><a href="http://felix.apache.org/site/dive-into-the-ipojo-manipulation-depths.html" title="Dive into the iPOJO Manipulation depths">Dive into the iPOJO Manipulation depths</a></li>
-</ul>
-
-
-<h6><a name="EventAdminHandlers-Misc&Contact"></a><b>Misc & Contact</b></h6>
-<ul>
- <li><a href="http://felix.apache.org/site/apache-felix-ipojo-issuestracker.html" title="apache-felix-ipojo-issuestracker">Issues Tracker</a></li>
- <li><a href="http://felix.apache.org/site/apache-felix-ipojo-supportedvms.html" title="apache-felix-ipojo-supportedVMs">Supported JVMs</a></li>
- <li><a href="http://felix.apache.org/site/apache-felix-ipojo-supportedosgi.html" title="apache-felix-ipojo-supportedOSGi">Supported OSGi Implementations</a></li>
- <li><span class="nobr"><a href="http://ipojo-dark-side.blogspot.com/" title="Visit page outside Confluence" rel="nofollow">iPOJO's Dark Side Blog<sup><img class="rendericon" src="event-admin-handlers_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
- <li><a href="http://felix.apache.org/site/future-ideas.html" title="Future Ideas">Future Ideas</a></li>
- <li><a href="http://felix.apache.org/site/contact.html" title="Contact">Contact</a></li>
- <li><a href="http://felix.apache.org/site/related-works.html" title="Related Works">Related Works</a></li>
- <li><a href="http://felix.apache.org/site/article-presentations.html" title="Article & Presentations">Article & Presentations</a></li>
-</ul>
-
-
-<hr>
-<div class="" align="center">
-<p><span class="nobr"><a href="http://cwiki.apache.org/confluence/createrssfeed.action?types=blogpost&statuses=created&statuses=modified&spaces=FELIX&labelString=iPOJO&rssType=atom&maxResults=10&timeSpan=5&publicFeed=true&title=iPOJO%20Atom%20Feed" title="Stay tuned!" rel="nofollow"><img src="event-admin-handlers_files/feed-icon-32x32.png" align="absmiddle" border="0"><sup><img class="rendericon" src="event-admin-handlers_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></p></div>
+ </div>
+ <img src="event-admin-handlers_files/footer.png" class="footer">
+</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 src="event-admin-handlers_files/ga.js" type="text/javascript"></script>
<script type="text/javascript">
+try{
var pageTracker = _gat._getTracker("UA-1518442-4");
pageTracker._trackPageview();
+} catch(err) {}
</script>
-</td></tr></tbody></table>
+
</div>
</body></html>
\ No newline at end of file