| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE- 2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <head> |
| <title>Apache Felix - Event Admin Handlers</title> |
| <link rel="icon" href="/res/favicon.ico"> |
| |
| <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="description" content="The most powerful component model for OSGi"> |
| |
| |
| <link href="/ipojo/web/bootstrap/css/bootstrap-cerulean.css" rel="stylesheet"> |
| <link href="/ipojo/web/bootstrap/css/bootstrap-responsive.css" rel="stylesheet"> |
| <link href="/ipojo/web/bootstrap/css/font-awesome.min.css" rel="stylesheet"> |
| <link href="/ipojo/web/style.css" rel="stylesheet"> |
| |
| <!-- Overide alert's colors --> |
| <link href="/ipojo/web/bootstrap/css/alert.css" rel="stylesheet"> |
| |
| <link rel="stylesheet" href="/ipojo/web/github.css" type="text/css" media="all"> |
| |
| |
| <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script> |
| <script src="/ipojo/web/bootstrap/js/bootstrap.min.js"></script> |
| |
| </head> |
| |
| <body data-spy="scroll" data-target=".subnav"> |
| <div class="navbar navbar-fixed-top navbar-inverse"> |
| <div class="navbar-inner"> |
| <div class="container"> |
| <a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse"> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </a> |
| <a class="brand" href="/documentation/subprojects/apache-felix-ipojo.html">Apache Felix iPOJO</a> |
| |
| <div class="nav-collapse" id="main-menu"> |
| <ul class="nav" id="main-menu-left"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/ipojo-news.html">News</a></li> |
| <li><a href="http://felix.apache.org/downloads.cgi">Downloads</a></li> |
| |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Tutorials <b class="caret"></b></a> |
| <ul class="dropdown-menu" id="tutorials-menu"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-why-choose-ipojo.html">Why choose iPOJO</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-successstories.html">Success stories</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-feature-overview.html">Features</a></li> |
| <li class="divider"></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-in-10-minutes.html">iPOJO in 10 minutes</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/how-to-use-ipojo-annotations.html">Using Annotations</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-hello-word-maven-based-tutorial.html">Maven tutorial</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-advanced-tutorial.html">Advanced tutorial</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/apache-felix-ipojo-dosgi.html">Using Distributed OSGi</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-composition-tutorial.html">Application Composition</a></li> |
| </ul> |
| </li> |
| |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Documentation <b class="caret"></b></a> |
| <ul class="dropdown-menu" id="user-guide-menu"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/service-requirement-handler.html">Requiring a service</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/providing-osgi-services.html">Providing a service</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/lifecycle-callback-handler.html">Lifecycle management</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/configuration-handler.html">Configuration</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/architecture-handler.html">Introspection</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/controller-lifecycle-handler.html">Impacting the lifecycle</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/injecting-bundle-context.html">Accessing the Bundle Context</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/apache-felix-ipojo-instances.html">Creating instances</a></li> |
| <li class="divider"></li> |
| <li class="dropdown-submenu"> |
| <a tabindex="-1" href="#">External <em>handlers</em></a> |
| <ul class="dropdown-menu"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/event-admin-handlers.html">Asynchronous communication</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/ipojo-jmx-handler.html">JMX management</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/extender-pattern-handler.html">Extender pattern</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/white-board-pattern-handler.html">Whiteboard pattern</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/temporal-service-dependency.html">Temporal dependencies</a></li> |
| </ul> |
| </li> |
| <li class="dropdown-submenu"> |
| <a tabindex="-1" href="#">Configuration Admin & Factories</a> |
| <ul class="dropdown-menu"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/combining-ipojo-and-configuration-admin.html">iPOJO and config admin</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-factory-service.html">Using the iPOJO Factory service</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/how-to-use-ipojo-factories.html">Factories and Instances</a></li> |
| </ul> |
| </li> |
| <li class="divider"></li> |
| <li class="dropdown-submenu"> |
| <a tabindex="-1" href="#">Advanced topics</a> |
| <ul class="dropdown-menu"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/instance-vs-service-controller.html">Instance vs. Service Controllers</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/service-binding-interceptors.html">Service Binding Interceptors</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/using-xml-schemas.html">XML Schemas</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/apache-felix-ipojo-api.html">Using the iPOJO API</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/constructing-pojo-objects-with-factory-methods.html">Constructing service objects with factory methods</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/using-ipojo-introspection-api.html">Using the introspection API</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-testing-components.html">Testing components</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/using-stereotypes.html">Using @Stereotypes</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-eclipse-integration.html">Eclipse Integration</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-extender-configuration.html">Configuring iPOJO's Extender</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-faq.html">FAQ</a></li> |
| <li class="divider"></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/how-to-write-your-own-handler.html">Handler development</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/how-to-use-ipojo-manipulation-metadata.html">Manipulation Metadata </a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/dive-into-the-ipojo-manipulation-depths.html">Dive into the iPOJO Manipulation depths</a></li> |
| <li><a href="http://felix.apache.org/ipojo/api/1.12.1">Javadoc</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| |
| <li class="dropdown" id="tools-menu"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Tools <b class="caret"></b></a> |
| <ul class="dropdown-menu" id="swatch-menu"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-ant-task.html">Ant Task</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-maven-plug-in.html">Maven Plugin</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-arch-command.html">Architecture commands</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/apache-felix-ipojo-online-manipulator.html">Online Manipulator</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-webconsole-plugin.html">Webconsole plugin</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-karaf-feature.html">Apache Karaf Features</a></li> |
| </ul> |
| </li> |
| |
| <li class="dropdown" id="community-menu"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Community <b class="caret"></b></a> |
| <ul class="dropdown-menu" id="swatch-menu"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/ipojo-support.html">Support</a></li> |
| <li><a href="http://www.apache.org/">ASF</a></li> |
| <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li> |
| <li><a href="http://www.apache.org/foundation/thanks.html">Sponsors</a></li> |
| </ul> |
| </li> |
| |
| <li class="dropdown" id="misc-menu"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Misc <b class="caret"></b></a> |
| <ul class="dropdown-menu" id="swatch-menu"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-supportedvms.html">Supported JVMs</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-supportedosgi.html">Supported OSGi Implementations</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/articles-and-presentations.html">Article & Presentations</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/developing-camel-mediators-with-ipojo.html">Developping Camel mediators with iPOJO</a></li> |
| </ul> |
| </li> |
| </ul> |
| <ul class="nav pull-right" id="main-menu-right"> |
| <li><a rel="tooltip" target="_blank" href="http://felix.apache.org">Apache Felix <i class="icon-share-alt"></i></a></li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| <div class="container"> |
| <div class="content"> |
| <style type="text/css"> |
| /* The following code is added by mdx_elementid.py |
| It was originally lifted from http://subversion.apache.org/style/site.css */ |
| /* |
| * Hide class="elementid-permalink", except when an enclosing heading |
| * has the :hover property. |
| */ |
| .headerlink, .elementid-permalink { |
| visibility: hidden; |
| } |
| h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style> |
| <h1 id="event-admin-handlers">Event Admin Handlers<a class="headerlink" href="#event-admin-handlers" title="Permanent link">¶</a></h1> |
| <p><em>The goal of the Event Admin Handlers is to allow event communications between iPOJO component instances. The implementation of these handlers relies on an event admin services. It enables the iPOJO component to listen to a list of topics and to receive all related events. It also allows components to send events in an easy way.</em></p> |
| <div class="toc"> |
| <ul> |
| <li><a href="#event-admin-handlers">Event Admin Handlers</a><ul> |
| <li><a href="#an-example">An example</a></li> |
| <li><a href="#download">Download</a></li> |
| <li><a href="#how-does-it-work">How does it work?</a></li> |
| <li><a href="#eventhandler-specification">EventHandler Specification</a><ul> |
| <li><a href="#event-subscriber-attributes">Event subscriber attributes</a></li> |
| <li><a href="#event-publisher-attributes">Event publisher attributes</a></li> |
| <li><a href="#instance-configuration">Instance configuration</a></li> |
| <li><a href="#publisher-interface">Publisher interface</a></li> |
| </ul> |
| </li> |
| <li><a href="#handler-architecture">Handler Architecture</a></li> |
| <li><a href="#eventhandler-features">EventHandler Features</a><ul> |
| <li><a href="#instance-customization">Instance customization</a></li> |
| <li><a href="#data-events">Data events</a></li> |
| <li><a href="#note-on-synchronous-event-sending">Note on synchronous event sending</a></li> |
| <li><a href="#publisher-instance-information">Publisher instance information</a></li> |
| <li><a href="#configuring-the-handler-with-annotations">Configuring the handler with annotations</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| <div class="alert alert-warning" markdown="1"> |
| <strong>change in the 1.2.0</strong> |
| <p>The 1.2.0 version use the namespace : <code>org.apache.felix.ipojo.handlers.event</code> instead of <code>org.apache.felix.ipojo.handlers.event.EventAdminHandler</code>.</p> |
| </div> |
| |
| <div class="alert alert-warning" markdown="1"> |
| <strong>change in the 1.7.0</strong> |
| <p>The <code>@Publisher</code> annotation is now deprecated and replaced by <code>@Publishes</code>.</p> |
| </div> |
| |
| <h2 id="an-example">An example<a class="headerlink" href="#an-example" title="Permanent link">¶</a></h2> |
| <p>Hereafter is presented a small example :</p> |
| <div class="codehilite"><pre><span class="nd">@Component</span> |
| <span class="nd">@Instantiate</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyComponent</span> <span class="o">{</span> |
| |
| <span class="nd">@Publishes</span><span class="o">(</span> <span class="c1">// or @Publisher before the 1.7.0</span> |
| <span class="n">name</span><span class="o">=</span><span class="s">"myPublisher"</span><span class="o">,</span> |
| <span class="n">topics</span><span class="o">=</span><span class="s">"bar,nuts"</span><span class="o">)</span> |
| <span class="kd">private</span> <span class="n">Publisher</span> <span class="n">m_publisher</span><span class="o">;</span> |
| |
| <span class="nd">@Subscriber</span><span class="o">(</span> |
| <span class="n">name</span><span class="o">=</span><span class="s">"mySubscriber"</span><span class="o">,</span> |
| <span class="n">topics</span><span class="o">=</span><span class="s">"foo"</span><span class="o">)</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">receive</span><span class="o">(</span><span class="n">Event</span> <span class="n">e</span><span class="o">)</span> <span class="o">{</span> |
| <span class="c1">// Event received</span> |
| <span class="c1">// Do something with the event</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>This component can also be described using the XML formalism:</p> |
| <div class="codehilite"><pre><span class="nt"><ipojo</span> |
| <span class="na">xmlns:ev=</span><span class="s">"org.apache.felix.ipojo.handlers.event"</span><span class="nt">></span> |
| <span class="nt"><component</span> <span class="na">className=</span><span class="s">"...MyComponent"</span><span class="nt">></span> |
| <span class="nt"><ev:subscriber</span> |
| <span class="na">name=</span><span class="s">"mySubscriber"</span> |
| <span class="na">callback=</span><span class="s">"receive"</span> |
| <span class="na">topics=</span><span class="s">"foo"</span><span class="nt">/></span> |
| <span class="nt"><ev:publisher</span> |
| <span class="na">name=</span><span class="s">"myPublisher"</span> |
| <span class="na">field=</span><span class="s">"m_publisher"</span> |
| <span class="na">topics=</span><span class="s">"bar,nuts"</span><span class="nt">/></span> |
| <span class="nt"></component></span> |
| <span class="nt"><instance</span> <span class="na">component=</span><span class="s">"...MyComponent"</span><span class="nt">/></span> |
| <span class="nt"></ipojo></span> |
| </pre></div> |
| |
| |
| <p>In XML, you need to specify the namespace of the Handler. You can find here one event subscriber (named mySubscriber) and one event publisher (named myPublisher). In these handler configurations, the name parameter is mandatory. The topics parameter is optional as it can be specified in the instance configuration. The callback parameter of the mySubscriber element is mandatory and indicates the method that handles received events. In this case, this method must have a single argument of type org.osgi.service.event.Event. The field parameter of the myPublisher element indicates the field (of type org.apache.felix.ipojo.handlers.event.publisher.Publisher) that is used by the POJO to send events on the specified topics. All type compliance will be checked by the handler at component instantiation time.</p> |
| <h2 id="download">Download<a class="headerlink" href="#download" title="Permanent link">¶</a></h2> |
| <p>The event admin handlers (to send and receive events) are available in the Felix trunk in the iPOJO project. See the <a href="/documentation/subprojects/apache-felix-ipojo/download.html">Download</a> page to download and compile these sources.</p> |
| <h2 id="how-does-it-work">How does it work?<a class="headerlink" href="#how-does-it-work" title="Permanent link">¶</a></h2> |
| <p>The handler will parse the description provided in the metadata, and register for you the EventHandler in the OSGi Registry. On one hand, your POJO will receive each event through the handler. With this handler you can specify different callback methods for different topics. On the other side, the handler instantiates and injects configured Publisher references in your POJO, so you can send events transparently through these publishers.</p> |
| <h2 id="eventhandler-specification">EventHandler Specification<a class="headerlink" href="#eventhandler-specification" title="Permanent link">¶</a></h2> |
| <p>Here you can find all configuration options of the EventAdmin handler. As seen before, the handler contains two components : the event subscriber and the event publisher. These components can be configured, using several attributes, as described below. Some of these attributes can be (re)defined in the instance configuration.</p> |
| <p><em>Handler namespace :</em> <em>org.apache.felix.ipojo.handlers.event</em></p> |
| <h3 id="event-subscriber-attributes">Event subscriber attributes<a class="headerlink" href="#event-subscriber-attributes" title="Permanent link">¶</a></h3> |
| <table class="table table-bordered"> |
| <thead> |
| <tr> |
| <th>Attribute name</th> |
| <th>Required</th> |
| <th>Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>name</td> |
| <td>yes</td> |
| <td>The name of the event subscriber, acting as a unique identifier.</td> |
| </tr> |
| <tr> |
| <td>callback</td> |
| <td>yes</td> |
| <td>The name of the POJO's method that will be called each time an event is received. This method takes only one parameter, of type <code>org.osgi.service.event.Event</code> by default, but this type can be overridden by defining the data-key and/or the data-type attributes.</td> |
| </tr> |
| <tr> |
| <td>topics</td> |
| <td>yes</td> |
| <td>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. The topics can be set in the instance configuration.</td> |
| </tr> |
| <tr> |
| <td>filter</td> |
| <td>no</td> |
| <td>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 Event Admin Specification. If you don't specify a filter, all events sent on the listened topics will be considered. The filter can be set in the instance configuration.</td> |
| </tr> |
| <tr> |
| <td>data-key</td> |
| <td>no</td> |
| <td>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. If you use this attribute, the parameter passed to the callback method is the the value associated to this key, not the whole event. This attribute is generally used with the **data-type** attribute to specify the received object type. If an event is received and it does not contain such a key, it is ignored (with a warning message).</td> |
| </tr> |
| <tr> |
| <td>data-type</td> |
| <td>no</td> |
| <td>This attribute is associated to the data-key attribute. It specifies the type of objects (<code>java.lang.Object</code> by 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. Data events that are not corresponding to the specified type will be ignored (with a warning message).</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <h3 id="event-publisher-attributes">Event publisher attributes<a class="headerlink" href="#event-publisher-attributes" title="Permanent link">¶</a></h3> |
| <p><table class="table table-bordered"> |
| <thead> |
| <tr> |
| <th>Attribute name</th> |
| <th>Required</th> |
| <th>Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>name</td> |
| <td>yes</td> |
| <td>The name of the event publisher, acting as a unique identifier.</td> |
| </tr> <br /> |
| <tr> |
| <td>field</td> |
| <td>yes</td> |
| <td>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 : <code>org.apache.felix.ipojo.handlers.event.publisher.Publisher</code>. 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>topics</td> |
| <td>yes</td> |
| <td>The comma-separated-list of the topics on which events will be sent. Topics can be set in the instance configuration</td> |
| </tr> |
| <tr> |
| <td>data-key</td> |
| <td>no</td> |
| <td>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 <code>sendData</code> method of the Publisher, the given object is placed in the event dictionary, associated with the specified data-key. The default value of this attribute is <code>user.data</code>.</td> |
| </tr> |
| <tr> |
| <td>synchronous</td> |
| <td>no</td> |
| <td>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.</td> |
| </tr> |
| </tbody> |
| </table></p> |
| <h3 id="instance-configuration">Instance configuration<a class="headerlink" href="#instance-configuration" title="Permanent link">¶</a></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 id="publisher-interface">Publisher interface<a class="headerlink" href="#publisher-interface" title="Permanent link">¶</a></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><code>public void send(Dictionary content)</code> : 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><code>public void sendData(Object o)</code> : 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 regular event.</li> |
| </ul> |
| <h2 id="handler-architecture">Handler Architecture<a class="headerlink" href="#handler-architecture" title="Permanent link">¶</a></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="handler-arch.png"></p> |
| <h2 id="eventhandler-features">EventHandler Features<a class="headerlink" href="#eventhandler-features" title="Permanent link">¶</a></h2> |
| <p>In this section, you will find some examples of the handler's features.</p> |
| <h3 id="instance-customization">Instance customization<a class="headerlink" href="#instance-customization" title="Permanent link">¶</a></h3> |
| <p>As described in the 'Instance configuration' section, you can (re)define some of the subscribers or publishers attributes. You can notice that required attributes that are not defined in the component description must be defined in the instance configuration section. Hereafter is an example of an instance configuration of this handler :</p> |
| <div class="codehilite"><pre><span class="nt"><ipojo></span> |
| <span class="nt"><instance</span> <span class="na">component=</span><span class="s">"...MyComponent"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"event.topics"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"mySubscriber"</span> <span class="na">value=</span><span class="s">"foo"</span><span class="nt">/></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"myPublisher"</span> <span class="na">value=</span><span class="s">"bar,nuts"</span><span class="nt">/></span> |
| <span class="nt"></property></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"event.filter"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"mySubscriber"</span> |
| <span class="na">value=</span><span class="s">"|((arg=Minibar)(arg=Coconuts))"</span><span class="nt">/></span> |
| <span class="nt"></property></span> |
| <span class="nt"></instance></span> |
| <span class="nt"></ipojo></span> |
| </pre></div> |
| |
| |
| <h3 id="data-events">Data events<a class="headerlink" href="#data-events" title="Permanent link">¶</a></h3> |
| <p>One of the most important features of the EventHandler is the capability of sending and receiving data events. You may know that the OSGi EventAdmin Service allows bundles to send custom objects in events, inserting them in the event's dictionary. The EventHandler hides the dictionary manipulation and allows iPOJO components to receive custom objects at any time.</p> |
| <p>First, you have define the <em>data-key</em> attribute in the publisher configuration (<code>dataKey</code> in annotations). Sent objects will be contained in the event dictionary and are accessible with the "user.data" key. </p> |
| <div class="codehilite"><pre><span class="nt"><ipojo</span> |
| <span class="na">xmlns:ev=</span><span class="s">"org.apache.felix.ipojo.handlers.event"</span><span class="nt">></span> |
| <span class="nt"><component</span> <span class="na">className=</span><span class="s">"...DataPublisher"</span><span class="nt">></span> |
| <span class="nt"><ev:publisher</span> |
| <span class="na">name=</span><span class="s">"myPublisher"</span> |
| <span class="na">field=</span><span class="s">"m_publisher"</span> |
| <span class="na">topics=</span><span class="s">"myTopic"</span> |
| <span class="na">data-key=</span><span class="s">"my.data"</span><span class="nt">/></span> |
| <span class="nt"></component></span> |
| <span class="nt"><instance</span> <span class="na">component=</span><span class="s">"...DataPublisher"</span><span class="nt">/></span> |
| <span class="nt"></ipojo></span> |
| </pre></div> |
| |
| |
| <p>Then you can use the <em>sendData</em> method of your configured publisher.</p> |
| <div class="codehilite"><pre><span class="kn">import</span> <span class="nn">org.apache.felix.ipojo.handlers.event.publisher.Publisher</span><span class="o">;</span> |
| <span class="c1">//...</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">DataPublisher</span> <span class="o">...</span> <span class="o">{</span> |
| <span class="kd">private</span> <span class="n">Publisher</span> <span class="n">m_publisher</span><span class="o">;</span> |
| |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">doSomething</span><span class="o">()</span> <span class="o">{</span> |
| <span class="c1">// MyFavoriteType extends MyFavoriteInterface</span> |
| <span class="n">MyFavoriteType</span> <span class="n">data</span> <span class="o">=</span> <span class="k">new</span> <span class="n">MyFavoriteType</span><span class="o">(...);</span> |
| <span class="c1">//...</span> |
| <span class="c1">// Send a data event</span> |
| <span class="n">m_publisher</span><span class="o">.</span><span class="na">sendData</span><span class="o">(</span><span class="n">data</span><span class="o">);</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>The second step is to configure an event subscriber to receive such events. The <em>data-key</em> attribute's value of the subscriber must be the same than the publisher's one. The <em>data-type</em> describes the type of received data events, and thus, must be compatible with the sent object's type (i.e., super-class or inherited interface). Then you can finally receive the sent object in the callback method. The parameter type of the callback must be the same than the data-type attribute value.</p> |
| <div class="codehilite"><pre><span class="nt"><ipojo</span> |
| <span class="na">xmlns:ev=</span><span class="s">"org.apache.felix.ipojo.handlers.event"</span><span class="nt">></span> |
| <span class="nt"><component</span> <span class="na">className=</span><span class="s">"...DataEventSubscriber"</span><span class="nt">></span> |
| <span class="nt"><ev:subscriber</span> |
| <span class="na">name=</span><span class="s">"mySubscriber"</span> |
| <span class="na">callback=</span><span class="s">"handleData"</span> |
| <span class="na">topics=</span><span class="s">"myTopic"</span> |
| <span class="na">data-key=</span><span class="s">"my.data"</span> |
| <span class="na">data-type=</span><span class="s">"my.package.MyFavoriteInterface"</span><span class="nt">/></span> |
| <span class="nt"></component></span> |
| <span class="nt"><instance</span> <span class="na">component=</span><span class="s">"...DataEventSubscriber"</span><span class="nt">/></span> |
| <span class="nt"></ipojo></span> |
| </pre></div> |
| |
| |
| <p> </p> |
| <div class="codehilite"><pre><span class="kn">import</span> <span class="nn">my.package.MyFavoriteInterface</span><span class="o">;</span> |
| <span class="c1">//...</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">DataEventSubscriber</span> <span class="o">...</span> <span class="o">{</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">handleData</span><span class="o">(</span><span class="n">MyFavoriteInterface</span> <span class="n">o</span><span class="o">)</span> <span class="o">{</span> |
| <span class="c1">// Object received</span> |
| <span class="c1">//...</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>Annotations use a different set of attributes:</p> |
| <ul> |
| <li>data-key is replaced by <code>dataKey</code></li> |
| <li>data-type is replaced by <code>dataType</code></li> |
| </ul> |
| <h3 id="note-on-synchronous-event-sending">Note on synchronous event sending<a class="headerlink" href="#note-on-synchronous-event-sending" title="Permanent link">¶</a></h3> |
| <p>By default, events are sent using asynchronous sending (a.k.a.<em>post</em> in OSGi EventAdmin). You can use synchronous sending by defining the <em>synchronous</em> attribute of your publisher to true.</p> |
| <p>The behavior of synchronous event sending is particular when you specify several topics in the publisher description. The event is synchronously sent to each topic, one by one. So when you return from this function, you can be sure that the event has been delivered to each topic.</p> |
| <h3 id="publisher-instance-information">Publisher instance information<a class="headerlink" href="#publisher-instance-information" title="Permanent link">¶</a></h3> |
| <p>All events sent by a publisher contains the name of the component instance that sent them. Its enables to filter received events depending the sender instance. The instance name is accessible in the event dictionary by the key <em>publisher.instance.name</em>. Despite it goes against MOM principles, this property is useful to trace events and especially event sources.</p> |
| <h3 id="configuring-the-handler-with-annotations">Configuring the handler with annotations<a class="headerlink" href="#configuring-the-handler-with-annotations" title="Permanent link">¶</a></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="codehilite"><pre><span class="kn">import</span> <span class="nn">org.apache.felix.ipojo.annotations.Component</span><span class="o">;</span> |
| <span class="kn">import</span> <span class="nn">org.apache.felix.ipojo.handlers.event.Subscriber</span><span class="o">;</span> |
| <span class="kn">import</span> <span class="nn">org.apache.felix.ipojo.handlers.event.Publishes</span><span class="o">;</span> |
| <span class="kn">import</span> <span class="nn">org.apache.felix.ipojo.handlers.event.publisher.Publisher</span><span class="o">;</span> |
| <span class="kn">import</span> <span class="nn">org.osgi.service.event.Event</span><span class="o">;</span> |
| |
| |
| <span class="nd">@Component</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">PubSub</span> <span class="o">{</span> |
| <span class="nd">@Publishes</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="s">"p1"</span><span class="o">,</span> <span class="n">synchronous</span><span class="o">=</span><span class="kc">true</span><span class="o">)</span> |
| <span class="n">Publisher</span> <span class="n">publisher1</span><span class="o">;</span> |
| |
| <span class="nd">@Publishes</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="s">"p2"</span><span class="o">,</span> <span class="n">synchronous</span><span class="o">=</span><span class="kc">false</span><span class="o">,</span> <span class="n">topics</span><span class="o">=</span><span class="s">"foo,bar"</span><span class="o">,</span> <span class="n">data_key</span><span class="o">=</span><span class="s">"data"</span><span class="o">)</span> |
| <span class="n">Publisher</span> <span class="n">publisher2</span><span class="o">;</span> |
| |
| <span class="nd">@Publishes</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="s">"p3"</span><span class="o">,</span> <span class="n">synchronous</span><span class="o">=</span><span class="kc">true</span><span class="o">,</span> <span class="n">topics</span><span class="o">=</span><span class="s">"bar"</span><span class="o">)</span> |
| <span class="n">Publisher</span> <span class="n">publisher3</span><span class="o">;</span> |
| |
| <span class="nd">@Subscriber</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="s">"s1"</span><span class="o">,</span> <span class="n">data_key</span><span class="o">=</span><span class="s">"data"</span><span class="o">)</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">receive1</span><span class="o">(</span><span class="n">Object</span> <span class="n">foo</span><span class="o">)</span> <span class="o">{</span> |
| <span class="c1">// Process event</span> |
| <span class="o">}</span> |
| |
| <span class="nd">@Subscriber</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="s">"s2"</span><span class="o">,</span> <span class="n">topics</span><span class="o">=</span><span class="s">"foo,bar"</span><span class="o">,</span> <span class="n">filter</span><span class="o">=</span><span class="s">"(foo=true)"</span><span class="o">)</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">receive2</span><span class="o">(</span><span class="n">Event</span> <span class="n">foo</span><span class="o">)</span> <span class="o">{</span> |
| <span class="c1">// Process event</span> |
| <span class="o">}</span> |
| |
| <span class="nd">@Subscriber</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="s">"s3"</span><span class="o">,</span> <span class="n">topics</span><span class="o">=</span><span class="s">"foo"</span><span class="o">,</span> <span class="n">data</span><span class="o">*</span><span class="n">key</span><span class="o">=</span><span class="s">"data"</span><span class="o">,</span> <span class="n">data</span><span class="o">*</span><span class="n">type</span><span class="o">=</span><span class="s">"java.lang.String"</span><span class="o">)</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">receive3</span><span class="o">(</span><span class="n">String</span> <span class="n">foo</span><span class="o">)</span> <span class="o">{</span> |
| <span class="c1">// Process event</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| </div> |
| </div> |
| |
| <hr/> |
| |
| <div class="container"> |
| <footer id="footer"> |
| <div class="row"> |
| <div class="trademarkFooter span7"> |
| Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project |
| logo are trademarks of The Apache Software Foundation. All other marks mentioned |
| may be trademarks or registered trademarks of their respective owners. |
| </div> |
| <div class="timestamp span3 offset2"> |
| Rev. 1700393 by cziegeler on Tue, 1 Sep 2015 06:04:06 +0000 |
| </div> |
| </div> |
| </footer> |
| </div> |
| </body> |
| |
| <script type="text/javascript"> |
| var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); |
| document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); |
| </script> |
| |
| <script type="text/javascript"> |
| try{ |
| var pageTracker = _gat._getTracker("UA-1518442-4"); |
| pageTracker._trackPageview(); |
| } catch(err) {} |
| </script> |
| |
| </html> |
