blob: b9fc56e584a530e70279a664d77b98bb7a88ea34 [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html><head>
<title>Apache Felix - Event Admin Handlers</title>
<link rel="stylesheet" href="event-admin-handlers_files/site.css" type="text/css" media="all">
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head><body>
<div class="title"><div class="logo"><a href="http://felix.apache.org/site/index.html"><img alt="Apache Felix" src="event-admin-handlers_files/logo.png" border="0"></a></div><div class="header"><a href="http://www.apache.org/"><img alt="Apache" src="event-admin-handlers_files/apache.png" border="0"></a></div></div>
<div class="menu">
<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><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><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" frameborder="0" height="135" width="135"></iframe>
<p style="height: 100px;">
<!-- ApacheCon Ad -->
</p></li></ul> </div>
<div class="main">
<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 &amp; Presentations">Article &amp; 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><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.</em></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="dp-highlighter"><table class="dp-xml" border="0" cellpadding="0" cellspacing="0"><tbody><tr><td class="line1"><span></span><span class="tag">&lt;</span><span>ipojo&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;xmlns:<span class="attribute">ev</span><span>=</span><span class="attribute-value">"org.apache.felix.ipojo.handlers.event"</span><span>&gt;&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>component&nbsp;</span><span class="attribute">className</span><span>=</span><span class="attribute-value">"...MyComponent"</span><span>&gt;&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>ev:subscriber&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="attribute">name</span><span>=</span><span class="attribute-value">"mySubscriber"</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="attribute">callback</span><span>=</span><span class="attribute-value">"receive"</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="attribute">topics</span><span>=</span><span class="attribute-value">"foo"</span><span>/&gt;&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>ev:publisher&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="attribute">name</span><span>=</span><span class="attribute-value">"myPublisher"</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="attribute">field</span><span>=</span><span class="attribute-value">"m_publisher"</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="attribute">topics</span><span>=</span><span class="attribute-value">"bar,nuts"</span><span>/&gt;&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;/</span><span>component</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>instance&nbsp;</span><span class="attribute">component</span><span>=</span><span class="attribute-value">"...MyComponent"</span><span>/&gt;&nbsp;</span></td></tr><tr><td class="line2"><span class="tag">&lt;/</span><span>ipojo</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr></tbody></table></div><textarea style="display: none;" name="newcodemacro" class="xml:nocontrols:nogutter" rows="10" readonly="readonly">&lt;ipojo
xmlns:ev="org.apache.felix.ipojo.handlers.event"&gt;
&lt;component className="...MyComponent"&gt;
&lt;ev:subscriber
name="mySubscriber"
callback="receive"
topics="foo"/&gt;
&lt;ev:publisher
name="myPublisher"
field="m_publisher"
topics="bar,nuts"/&gt;
&lt;/component&gt;
&lt;instance component="...MyComponent"/&gt;
&lt;/ipojo&gt;</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
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>
<p>Here is an example of the component implementation, compatible with the given description :</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>&nbsp;org.apache.felix.ipojo.handlers.event.publisher.Publisher;&nbsp;</span></td></tr><tr><td class="line2"><span class="keyword">import</span><span>&nbsp;org.osgi.service.event.Event;&nbsp;</span></td></tr><tr><td class="line1">&nbsp;</td></tr><tr><td class="line2"><span class="keyword">public</span><span>&nbsp;</span><span class="keyword">class</span><span>&nbsp;MyComponent&nbsp;...&nbsp;{&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;<span class="keyword">private</span><span>&nbsp;Publisher&nbsp;m_publisher;&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;<span class="keyword">public</span><span>&nbsp;</span><span class="keyword">void</span><span>&nbsp;receive(Event&nbsp;e)&nbsp;{&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="comment">//&nbsp;Event&nbsp;received</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="comment">//&nbsp;Do&nbsp;something&nbsp;with&nbsp;the&nbsp;event}</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;</td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;<span class="keyword">public</span><span>&nbsp;</span><span class="keyword">void</span><span>&nbsp;doSomething()&nbsp;{&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Dictionary&nbsp;e&nbsp;=&nbsp;new&nbsp;Properties();&nbsp;</td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="comment">//...</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="comment">//&nbsp;Fill&nbsp;out&nbsp;the&nbsp;event</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;</td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="comment">//&nbsp;Send&nbsp;event</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;m_publisher.send(e);&nbsp;</td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;</td></tr><tr><td class="line2">}&nbsp;</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;
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);
}
}</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>
<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>
<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,
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><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
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><b>Handler namespace :</b> org.apache.felix.ipojo.handlers.event</p>
<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>
<th class="confluenceTh"> Description </th>
</tr>
<tr>
<td class="confluenceTd"> <em>name</em> </td>
<td class="confluenceTd"> YES </td>
<td class="confluenceTd"> The name of the event subscriber, acting as a unique identifier. </td>
</tr>
<tr>
<td class="confluenceTd"> <em>callback</em> </td>
<td class="confluenceTd"> YES </td>
<td class="confluenceTd"> 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. </td>
</tr>
<tr>
<td class="confluenceTd"> <em>topics</em> </td>
<td class="confluenceTd"> YES* </td>
<td class="confluenceTd"> 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. </td>
</tr>
<tr>
<td class="confluenceTd"> <em>data-key</em> </td>
<td class="confluenceTd"> NO </td>
<td class="confluenceTd"> The data key is used when you want to receive
data events. This attribute's value is the key corresponding to the
received data in the event's dictionary. <br clear="all">
If you use this attribute, the parameter passed to the callback method
is the the value associated to this key, not the whole event. <br clear="all">
This attribute is generally used with the <em>data-type</em> attribute to specify the received object type. <br clear="all">
If an event is received and it does not contain such a key, it is ignored (with a warning message). </td>
</tr>
<tr>
<td class="confluenceTd"> <em>data-type</em> </td>
<td class="confluenceTd"> NO </td>
<td class="confluenceTd"> This attribute is associated to the data-key
attribute. It specifies the type of objects (java.lang.Objectby
default) that the callback expects. It is used to determine the unique
callback method (in case of multiple methods with the same name) and to
check type compliance at event reception. <br clear="all">
Data events that are not corresponding to the specified type will be ignored (with a warning message). </td>
</tr>
<tr>
<td class="confluenceTd"> <em>filter</em> </td>
<td class="confluenceTd"> NO* </td>
<td class="confluenceTd"> 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. </td>
</tr>
</tbody></table>
<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>
<th class="confluenceTh"> Description </th>
</tr>
<tr>
<td class="confluenceTd"> <em>name</em> </td>
<td class="confluenceTd"> YES </td>
<td class="confluenceTd"> The name of the event publisher, acting as a unique identifier. </td>
</tr>
<tr>
<td class="confluenceTd"> <em>field</em> </td>
<td class="confluenceTd"> YES </td>
<td class="confluenceTd"> 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. </td>
</tr>
<tr>
<td class="confluenceTd"> <em>topics</em> </td>
<td class="confluenceTd"> YES* </td>
<td class="confluenceTd"> The comma-separated-list of the topics on which events will be sent. </td>
</tr>
<tr>
<td class="confluenceTd"> <em>data-key</em> </td>
<td class="confluenceTd"> NO </td>
<td class="confluenceTd"> The data key is used when you want to send
data events. This attribute's value is the key, in the event's
dictionary, in which sent data are stored. When you use the <em>sendData</em> method of the Publisher, the given object is placed in the event dictionary, associated with the specified data-key. <br clear="all">
The default value of this attribute is user.data. </td>
</tr>
<tr>
<td class="confluenceTd"> <em>synchronous</em> </td>
<td class="confluenceTd"> NO </td>
<td class="confluenceTd"> Determines if event sending is synchronous or
not. By default, events are sent asynchronously, but you can specify
there the desired behaviour of the Publisher. <br clear="all">
The default value of this attribute is "false". </td>
</tr>
</tbody></table>
<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
event management instance by instance. The following properties are
used by the handler :</p>
<ul>
<li><em>event.topics</em> : overrides <em>topics</em> attribute, available for both subscribers and publishers configuration</li>
<li><em>event.filter</em> : overrides <em>filter</em> attribute, available for subscribers configuration only.</li>
</ul>
<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
the component's description (or instance configuration). The
implemented methods are :</p>
<ul>
<li>public void send<font color="#000000">(Dictionary content);</font><br>
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).</li>
<li>public void sendData<font color="#000000">(Object o);</font><br>
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.</li>
</ul>
<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" border="0" align="absmiddle"></p>
<h2><a name="EventAdminHandlers-EventHandlerFeatures"></a>EventHandler Features</h2>
<p>In this section, you will find some examples of the handler's features.</p>
<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="dp-highlighter"><table class="dp-xml" border="0" cellpadding="0" cellspacing="0"><tbody><tr><td class="line1"><span></span><span class="tag">&lt;</span><span>ipojo&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;xmlns:<span class="attribute">ev</span><span>=</span><span class="attribute-value">"org.apache.felix.ipojo.handlers.event"</span><span>&gt;&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>component&nbsp;</span><span class="attribute">className</span><span>=</span><span class="attribute-value">"...MyComponent"</span><span>&gt;&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>ev:subscriber&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="attribute">name</span><span>=</span><span class="attribute-value">"mySubscriber"</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="attribute">callback</span><span>=</span><span class="attribute-value">"handleEvent"</span><span>/&gt;&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>ev:publisher&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="attribute">name</span><span>=</span><span class="attribute-value">"myPublisher"</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="attribute">field</span><span>=</span><span class="attribute-value">"m_publisher"</span><span>/&gt;&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;/</span><span>component</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>instance&nbsp;</span><span class="attribute">component</span><span>=</span><span class="attribute-value">"...MyComponent"</span><span>&gt;&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>property&nbsp;</span><span class="attribute">name</span><span>=</span><span class="attribute-value">"event.topics"</span><span>&gt;&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>property&nbsp;</span><span class="attribute">name</span><span>=</span><span class="attribute-value">"mySubscriber"</span><span>&nbsp;</span><span class="attribute">value</span><span>=</span><span class="attribute-value">"foo"</span><span>/&gt;&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>property&nbsp;</span><span class="attribute">name</span><span>=</span><span class="attribute-value">"myPublisher"</span><span>&nbsp;</span><span class="attribute">value</span><span>=</span><span class="attribute-value">"bar,nuts"</span><span>/&gt;&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;/</span><span>property</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>property&nbsp;</span><span class="attribute">name</span><span>=</span><span class="attribute-value">"event.filter"</span><span>&gt;&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>property&nbsp;</span><span class="attribute">name</span><span>=</span><span class="attribute-value">"mySubscriber"</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="attribute">value</span><span>=</span><span class="attribute-value">"|((arg=Minibar)(arg=Coconuts))"</span><span>/&gt;&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;/</span><span>property</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;/</span><span>instance</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr><tr><td class="line1"><span class="tag">&lt;/</span><span>ipojo</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr></tbody></table></div><textarea style="display: none;" name="newcodemacro" class="xml:nocontrols:nogutter" rows="10" readonly="readonly">&lt;ipojo
xmlns:ev="org.apache.felix.ipojo.handlers.event"&gt;
&lt;component className="...MyComponent"&gt;
&lt;ev:subscriber
name="mySubscriber"
callback="handleEvent"/&gt;
&lt;ev:publisher
name="myPublisher"
field="m_publisher"/&gt;
&lt;/component&gt;
&lt;instance component="...MyComponent"&gt;
&lt;property name="event.topics"&gt;
&lt;property name="mySubscriber" value="foo"/&gt;
&lt;property name="myPublisher" value="bar,nuts"/&gt;
&lt;/property&gt;
&lt;property name="event.filter"&gt;
&lt;property name="mySubscriber"
value="|((arg=Minibar)(arg=Coconuts))"/&gt;
&lt;/property&gt;
&lt;/instance&gt;
&lt;/ipojo&gt;</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-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
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. Sent objects will be contained in the event
dictionary and are accessible with the "user.data" key.</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">&lt;</span><span>ipojo&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;xmlns:<span class="attribute">ev</span><span>=</span><span class="attribute-value">"org.apache.felix.ipojo.handlers.event"</span><span>&gt;&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>component&nbsp;</span><span class="attribute">className</span><span>=</span><span class="attribute-value">"...DataPublisher"</span><span>&gt;&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>ev:publisher&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="attribute">name</span><span>=</span><span class="attribute-value">"myPublisher"</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="attribute">field</span><span>=</span><span class="attribute-value">"m_publisher"</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="attribute">topics</span><span>=</span><span class="attribute-value">"myTopic"</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="attribute">data-key</span><span>=</span><span class="attribute-value">"my.data"</span><span>/&gt;&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;/</span><span>component</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>instance&nbsp;</span><span class="attribute">component</span><span>=</span><span class="attribute-value">"...DataPublisher"</span><span>/&gt;&nbsp;</span></td></tr><tr><td class="line1"><span class="tag">&lt;/</span><span>ipojo</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr></tbody></table></div><textarea style="display: none;" name="newcodemacro" class="xml:nocontrols:nogutter" rows="10" readonly="readonly">&lt;ipojo
xmlns:ev="org.apache.felix.ipojo.handlers.event"&gt;
&lt;component className="...DataPublisher"&gt;
&lt;ev:publisher
name="myPublisher"
field="m_publisher"
topics="myTopic"
data-key="my.data"/&gt;
&lt;/component&gt;
&lt;instance component="...DataPublisher"/&gt;
&lt;/ipojo&gt;</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>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>&nbsp;org.apache.felix.ipojo.handlers.event.publisher.Publisher;&nbsp;</span></td></tr><tr><td class="line2"><span class="comment">//...</span><span>&nbsp;</span></td></tr><tr><td class="line1"><span class="keyword">public</span><span>&nbsp;</span><span class="keyword">class</span><span>&nbsp;DataPublisher&nbsp;...&nbsp;{&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;<span class="keyword">private</span><span>&nbsp;Publisher&nbsp;m_publisher;&nbsp;</span></td></tr><tr><td class="line1">&nbsp;</td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;<span class="keyword">public</span><span>&nbsp;</span><span class="keyword">void</span><span>&nbsp;doSomething()&nbsp;{&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="comment">//&nbsp;MyFavoriteType&nbsp;extends&nbsp;MyFavoriteInterface</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;MyFavoriteType&nbsp;data&nbsp;=&nbsp;new&nbsp;MyFavoriteType(...);&nbsp;</td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="comment">//...</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="comment">//&nbsp;Send&nbsp;a&nbsp;data&nbsp;event</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;m_publisher.sendData(data);&nbsp;</td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;</td></tr><tr><td class="line1">}&nbsp;</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">&lt;</span><span>ipojo&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;xmlns:<span class="attribute">ev</span><span>=</span><span class="attribute-value">"org.apache.felix.ipojo.handlers.event"</span><span>&gt;&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>component&nbsp;</span><span class="attribute">className</span><span>=</span><span class="attribute-value">"...DataEventSubscriber"</span><span>&gt;&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>ev:subscriber&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="attribute">name</span><span>=</span><span class="attribute-value">"mySubscriber"</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="attribute">callback</span><span>=</span><span class="attribute-value">"handleData"</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="attribute">topics</span><span>=</span><span class="attribute-value">"myTopic"</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="attribute">data-key</span><span>=</span><span class="attribute-value">"my.data"</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="attribute">data-type</span><span>=</span><span class="attribute-value">"my.package.MyFavoriteInterface"</span><span>/&gt;&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;/</span><span>component</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;<span class="tag">&lt;</span><span>instance&nbsp;</span><span class="attribute">component</span><span>=</span><span class="attribute-value">"...DataEventSubscriber"</span><span>/&gt;&nbsp;</span></td></tr><tr><td class="line2"><span class="tag">&lt;/</span><span>ipojo</span><span class="tag">&gt;</span><span>&nbsp;</span></td></tr></tbody></table></div><textarea style="display: none;" name="newcodemacro" class="xml:nocontrols:nogutter" rows="10" readonly="readonly">&lt;ipojo
xmlns:ev="org.apache.felix.ipojo.handlers.event"&gt;
&lt;component className="...DataEventSubscriber"&gt;
&lt;ev:subscriber
name="mySubscriber"
callback="handleData"
topics="myTopic"
data-key="my.data"
data-type="my.package.MyFavoriteInterface"/&gt;
&lt;/component&gt;
&lt;instance component="...DataEventSubscriber"/&gt;
&lt;/ipojo&gt;</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>&nbsp;my.</span><span class="keyword">package</span><span>.MyFavoriteInterface;&nbsp;</span></td></tr><tr><td class="line2"><span class="comment">//...</span><span>&nbsp;</span></td></tr><tr><td class="line1"><span class="keyword">public</span><span>&nbsp;</span><span class="keyword">class</span><span>&nbsp;DataEventSubscriber&nbsp;...&nbsp;{&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;<span class="keyword">public</span><span>&nbsp;</span><span class="keyword">void</span><span>&nbsp;handleData(MyFavoriteInterface&nbsp;o)&nbsp;{&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="comment">//&nbsp;Object&nbsp;received</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="comment">//...</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;}&nbsp;</td></tr><tr><td class="line2">}&nbsp;</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>
<p>The behaviour 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><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
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><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="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>&nbsp;org.apache.felix.ipojo.annotations.Component;&nbsp;</span></td></tr><tr><td class="line2"><span class="keyword">import</span><span>&nbsp;org.apache.felix.ipojo.handlers.event.Subscriber;&nbsp;</span></td></tr><tr><td class="line1"><span class="keyword">import</span><span>&nbsp;org.osgi.service.event.Event;&nbsp;</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>&nbsp;</span></td></tr><tr><td class="line1"><span class="keyword">public</span><span>&nbsp;</span><span class="keyword">class</span><span>&nbsp;PubSub&nbsp;{&nbsp;</span></td></tr><tr><td class="line2"><span class="preprocessor">&nbsp;&nbsp;&nbsp;&nbsp;@org.apache.felix.ipojo.handlers.event.Publisher(name="p1",&nbsp;synchronous=true)</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;org.apache.felix.ipojo.handlers.event.publisher.Publisher&nbsp;publisher1;&nbsp;</td></tr><tr><td class="line2"><span class="preprocessor">&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr><tr><td class="line1"><span class="preprocessor">&nbsp;&nbsp;&nbsp;&nbsp;@org.apache.felix.ipojo.handlers.event.Publisher(name="p2",&nbsp;synchronous=false,&nbsp;topics="foo,bar",&nbsp;data_key="data")</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;org.apache.felix.ipojo.handlers.event.publisher.Publisher&nbsp;publisher2;&nbsp;</td></tr><tr><td class="line1"><span class="preprocessor">&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr><tr><td class="line2"><span class="preprocessor">&nbsp;&nbsp;&nbsp;&nbsp;@org.apache.felix.ipojo.handlers.event.Publisher(name="p3",&nbsp;synchronous=true,&nbsp;topics="bar")</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;org.apache.felix.ipojo.handlers.event.publisher.Publisher&nbsp;publisher3;&nbsp;</td></tr><tr><td class="line2"><span class="preprocessor">&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr><tr><td class="line1"><span class="preprocessor">&nbsp;&nbsp;&nbsp;&nbsp;@Subscriber(name="s1",&nbsp;data_key="data")</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;<span class="keyword">public</span><span>&nbsp;</span><span class="keyword">void</span><span>&nbsp;receive1(Object&nbsp;foo)&nbsp;{&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="comment">//&nbsp;Process&nbsp;event</span><span>&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;</td></tr><tr><td class="line1"><span class="preprocessor">&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr><tr><td class="line2"><span class="preprocessor">&nbsp;&nbsp;&nbsp;&nbsp;@Subscriber(name="s2",&nbsp;topics="foo,bar",&nbsp;filter="(foo=true)")</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;<span class="keyword">public</span><span>&nbsp;</span><span class="keyword">void</span><span>&nbsp;receive2(Event&nbsp;foo)&nbsp;{&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="comment">//&nbsp;Process&nbsp;event</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;</td></tr><tr><td class="line2"><span class="preprocessor">&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr><tr><td class="line1"><span class="preprocessor">&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr><tr><td class="line2"><span class="preprocessor">&nbsp;&nbsp;&nbsp;&nbsp;@Subscriber(name="s3",&nbsp;topics="foo",&nbsp;data_key="data",&nbsp;data_type="java.lang.String")</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;<span class="keyword">public</span><span>&nbsp;</span><span class="keyword">void</span><span>&nbsp;receive3(String&nbsp;foo)&nbsp;{&nbsp;</span></td></tr><tr><td class="line2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="comment">//&nbsp;Process&nbsp;event</span><span>&nbsp;</span></td></tr><tr><td class="line1">&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;</td></tr><tr><td class="line2">}&nbsp;</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
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="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="p3", synchronous=true, topics="bar")
org.apache.felix.ipojo.handlers.event.publisher.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
}
}</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><br clear="all"></p>
</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>
</div>
</body></html>