| <!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 & 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><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"><</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="mySubscriber" |
| callback="receive" |
| topics="foo"/> |
| <ev:publisher |
| 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 |
| 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> 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; |
| |
| 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"><</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="mySubscriber" |
| callback="handleEvent"/> |
| <ev:publisher |
| 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(); |
| } |
| } |
| } |
| |
| </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"><</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="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(); |
| } |
| } |
| } |
| |
| </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> |
| |
| <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> 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 |
| 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> |
