Gitiles
Code Review Sign In
gerrit.onosproject.org / onos-felix / 3e0db1ee7cdd5913117059a5a60e526d75fef1f0 / . / ipojo / handler / eventadmin / doc / event-admin-handlers.html
blob: 783515af3767002b7d088b694a61da921ac752f5 [file] [log] [blame]
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]2<html><head>
3
4
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]5
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]6 <title>Apache Felix - Event Admin Handlers</title>
7 <link rel="stylesheet" href="event-admin-handlers_files/site.css" type="text/css" media="all">
8 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
9 </head><body>
10 <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>
11 <div class="menu">
12<ul>
13 <li><a href="http://felix.apache.org/site/news.html" title="news">news</a></li>
14 <li><a href="http://felix.apache.org/site/license.html" title="license">license</a></li>
15 <li><span class="nobr"><a href="http://felix.apache.org/site/downloads.cgi" title="Visit page outside Confluence" rel="nofollow">downloads<sup><img class="rendericon" src="event-admin-handlers_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
16 <li><a href="http://felix.apache.org/site/documentation.html" title="documentation">documentation</a></li>
17 <li><a href="http://felix.apache.org/site/mailinglists.html" title="mailinglists">mailing lists</a></li>
18 <li><a href="http://felix.apache.org/site/contributing.html" title="Contributing">contributing</a></li>
19 <li><span class="nobr"><a href="http://www.apache.org/" title="Visit page outside Confluence" rel="nofollow">asf<sup><img class="rendericon" src="event-admin-handlers_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
20 <li><span class="nobr"><a href="http://www.apache.org/foundation/sponsorship.html" title="Visit page outside Confluence" rel="nofollow">sponsorship<sup><img class="rendericon" src="event-admin-handlers_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
21 <li><span class="nobr"><a href="http://www.apache.org/foundation/thanks.html" title="Visit page outside Confluence" rel="nofollow">sponsors<sup><img class="rendericon" src="event-admin-handlers_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]22<!-- ApacheCon Ad -->
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]23<iframe src="event-admin-handlers_files/button.html" style="border-width: 0pt; float: left;" scrolling="no" width="135" frameborder="0" height="135"></iframe>
24<p style="height: 100px;">
25<!-- ApacheCon Ad -->
26</p></li></ul> </div>
27 <div class="main">
28<table class="sectionMacro" border="0" cellpadding="5" cellspacing="0" width="100%"><tbody><tr>
29<td class="confluenceTd" valign="top" width="80%">
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]30
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]31<h1><a name="EventAdminHandlers-EventAdminHandlers"></a>Event Admin Handlers</h1>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]32
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]33<p>The goal of the Event Admin Handlers is to allow event
34communications between iPOJO component instances. The implementation of
35these handlers relies on an event admin services. It enables the iPOJO
36component to listen to a list of topics and to receive all related
37event. It also allows components to send events in an easy way.</p>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]38
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]39<p><b>UPDATE</b> : the 1.1.0-SNAPSHOT version has a new namespace : <tt>org.apache.felix.ipojo.handlers.event</tt> instead of <tt>org.apache.felix.ipojo.handlers.event.EventAdminHandler</tt></p>
40
41<p>Hereafter is presented a small example of the metadata.xml file :</p>
42<div class="code"><div class="codeContent">
43<pre class="code-xml">&lt;ipojo
44 <span class="code-keyword">xmlns:ev</span>=<span class="code-quote">"org.apache.felix.ipojo.handlers.event.EventAdminHandler"</span>&gt;
45 <span class="code-tag">&lt;component className=<span class="code-quote">"...MyComponent"</span>&gt;</span>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]46 &lt;ev:subscriber
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]47 name=<span class="code-quote">"mySubscriber"</span>
48 callback=<span class="code-quote">"receive"</span>
49 topics=<span class="code-quote">"foo"</span>/&gt;
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]50 &lt;ev:publisher
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]51 name=<span class="code-quote">"myPublisher"</span>
52 field=<span class="code-quote">"m_publisher"</span>
53 topics=<span class="code-quote">"bar,nuts"</span>/&gt;
54 <span class="code-tag">&lt;/component&gt;</span>
55 <span class="code-tag">&lt;instance component=<span class="code-quote">"...MyComponent"</span>/&gt;</span>
56<span class="code-tag">&lt;/ipojo&gt;</span></pre>
57</div></div>
58<p>You need to specify the namespace of the Handler. You can find here
59one event subscriber (named mySubscriber) and one event publisher
60(named myPublisher). In these handler configurations, the name
61parameter is mandatory. The topics parameter is optional as it can be
62specified in the instance configuration. The callback parameter of the
63mySubscriber element is mandatory and indicates the method that handles
64received events. In this case, this method must have a single argument
65of type org.osgi.service.event.Event. The field parameter of the
66myPublisher element indicates the field (of type
67org.apache.felix.ipojo.handlers.event.publisher.Publisher) that is used
68by the POJO to send events on the specified topics. All type compliance
69will be checked by the handler at component instantiation time.</p>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]70
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]71<p>Here is an example of the component implementation, compatible with the given description :</p>
72<div class="code"><div class="codeContent">
73<pre class="code-java"><span class="code-keyword">import</span> org.apache.felix.ipojo.handlers.event.publisher.Publisher;
74<span class="code-keyword">import</span> org.osgi.service.event.Event;
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]75
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]76<span class="code-keyword">public</span> class MyComponent ... {
77 <span class="code-keyword">private</span> Publisher m_publisher;
78 <span class="code-keyword">public</span> void receive(Event e) {
79 <span class="code-comment">// Event received
80</span> <span class="code-comment">// Do something with the event}
81</span>
82 <span class="code-keyword">public</span> void doSomething() {
83 Dictionary e = <span class="code-keyword">new</span> Properties();
84 <span class="code-comment">//...
85</span> <span class="code-comment">// Fill out the event
86</span>
87 <span class="code-comment">// Send event
88</span> m_publisher.send(e);
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]89 }
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]90}</pre>
91</div></div>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]92
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]93<h1><a name="EventAdminHandlers-Download"></a>Download</h1>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]94
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]95<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>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]96
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]97<h1><a name="EventAdminHandlers-Howdoesitwork?"></a>How does it work?</h1>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]98
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]99<p>The handler will parse the description provided in the metadata, and
100register for you the EventHandler in the OSGi Registry. On one hand,
101your POJO will receive each event through the handler. With this
102handler you can specify different callback methods for different
103topics. On the other side, the handler instantiates and injects
104configured Publisher references in your POJO, so you can send events
105transparently through these publishers.</p>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]106
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]107<h1><a name="EventAdminHandlers-EventHandlerSpecification"></a>EventHandler Specification</h1>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]108
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]109<p>Here you can find all configuration options of the EventAdmin
110handler. As seen before, the handler contains two components : the
111event subscriber and the event publisher. These components can be
112configured, using several attributes, as described below. Some of these
113attributes can be (re)defined in the instance configuration.</p>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]114
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]115<p>Handler namespace : org.apache.felix.ipojo.handlers.event.EventAdminHandler</p>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]116
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]117<h2><a name="EventAdminHandlers-Eventsubscriberattributes"></a>Event subscriber attributes</h2>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]118
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]119<table class="confluenceTable"><tbody>
120<tr>
121<th class="confluenceTh"> Attribute name </th>
122<th class="confluenceTh"> Required </th>
123<th class="confluenceTh"> Description </th>
124</tr>
125<tr>
126<td class="confluenceTd"> <em>name</em> </td>
127<td class="confluenceTd"> YES </td>
128<td class="confluenceTd"> The name of the event subscriber, acting as a unique identifier. </td>
129</tr>
130<tr>
131<td class="confluenceTd"> <em>callback</em> </td>
132<td class="confluenceTd"> YES </td>
133<td class="confluenceTd"> The name of the POJO's method that will be
134called each time an event is received. This method takes only one
135parameter, of typeorg.osgi.service.event.Eventby default, but this type
136can be overridden by defining the data-key and/or the data-type
137attributes. </td>
138</tr>
139<tr>
140<td class="confluenceTd"> <em>topics</em> </td>
141<td class="confluenceTd"> YES* </td>
142<td class="confluenceTd"> The comma-separated-list of the topics that
143the handler will listen to. Each event sent on a topic present in this
144list will be sent to the specified callback method. </td>
145</tr>
146<tr>
147<td class="confluenceTd"> <em>data-key</em> </td>
148<td class="confluenceTd"> NO </td>
149<td class="confluenceTd"> The data key is used when you want to receive
150data events. This attribute's value is the key corresponding to the
151received data in the event's dictionary. <br clear="all">
152If you use this attribute, the parameter passed to the callback method
153is the the value associated to this key, not the whole event. <br clear="all">
154This attribute is generally used with the <em>data-type</em> attribute to specify the received object type. <br clear="all">
155If an event is received and it does not contain such a key, it is ignored (with a warning message). </td>
156</tr>
157<tr>
158<td class="confluenceTd"> <em>data-type</em> </td>
159<td class="confluenceTd"> NO </td>
160<td class="confluenceTd"> This attribute is associated to the data-key
161attribute. It specifies the type of objects (java.lang.Objectby
162default) that the callback expects. It is used to determine the unique
163callback method (in case of multiple methods with the same name) and to
164check type compliance at event reception. <br clear="all">
165Data events that are not corresponding to the specified type will be ignored (with a warning message). </td>
166</tr>
167<tr>
168<td class="confluenceTd"> <em>filter</em> </td>
169<td class="confluenceTd"> NO* </td>
170<td class="confluenceTd"> The event filter is used to filter incoming
171events before sending them to the callback. The syntax of this field is
172described in the OSGi EventAdmin Specification. If you don't specify a
173filter, all events sent on the listened topics will be considered. </td>
174</tr>
175</tbody></table>
176<p>* These attributes can be (re)defined in the instance configuration.</p>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]177
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]178<h2><a name="EventAdminHandlers-Eventpublisherattributes"></a>Event publisher attributes</h2>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]179
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]180<table class="confluenceTable"><tbody>
181<tr>
182<th class="confluenceTh"> Attribute name </th>
183<th class="confluenceTh"> Required </th>
184<th class="confluenceTh"> Description </th>
185</tr>
186<tr>
187<td class="confluenceTd"> <em>name</em> </td>
188<td class="confluenceTd"> YES </td>
189<td class="confluenceTd"> The name of the event publisher, acting as a unique identifier. </td>
190</tr>
191<tr>
192<td class="confluenceTd"> <em>field</em> </td>
193<td class="confluenceTd"> YES </td>
194<td class="confluenceTd"> The name of the POJO's field that will be
195used to send events. The field is initialized at component
196instantiation time. The type of the field must be :
197org.apache.felix.ipojo.handlers.event.publisher.Publisher. Despite it
198creates a dependency between the component code and the handler, this
199system allows hiding the whole complexity of event sending. </td>
200</tr>
201<tr>
202<td class="confluenceTd"> <em>topics</em> </td>
203<td class="confluenceTd"> YES* </td>
204<td class="confluenceTd"> The comma-separated-list of the topics on which events will be sent. </td>
205</tr>
206<tr>
207<td class="confluenceTd"> <em>data-key</em> </td>
208<td class="confluenceTd"> NO </td>
209<td class="confluenceTd"> The data key is used when you want to send
210data events. This attribute's value is the key, in the event's
211dictionary, 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">
212The default value of this attribute is user.data. </td>
213</tr>
214<tr>
215<td class="confluenceTd"> <em>synchronous</em> </td>
216<td class="confluenceTd"> NO </td>
217<td class="confluenceTd"> Determines if event sending is synchronous or
218not. By default, events are sent asynchronously, but you can specify
219there the desired behaviour of the Publisher. <br clear="all">
220The default value of this attribute is "false". </td>
221</tr>
222</tbody></table>
223<p>* These attributes can be (re)defined in the instance configuration.</p>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]224
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]225<h2><a name="EventAdminHandlers-Instanceconfiguration"></a>Instance configuration</h2>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]226
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]227<p>Some of the described attributes can be (re)defined in the instance
228configuration section of your metadata file. Its permits to configure
229event management instance by instance. The following properties are
230used by the handler :</p>
231<ul>
232 <li><em>event.topics</em> : overrides <em>topics</em> attribute, available for both subscribers and publishers configuration</li>
233 <li><em>event.filter</em> : overrides <em>filter</em> attribute, available for subscribers configuration only.</li>
234</ul>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]235
236
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]237<h2><a name="EventAdminHandlers-Publisherinterface"></a>Publisher interface</h2>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]238
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]239<p>The Publisher interface is the link between the component code and
240the handler. It permits to publish events on the topics specified in
241the component's description (or instance configuration). The
242implemented methods are :</p>
243<ul>
244 <li>public void send<font color="#000000">(Dictionary content);</font><br>
245This method is used to send a standard event, with the specified
246content. Some specific properties may be added in the content to
247satisfy EventAdmin specification. (e.g., event.topic).</li>
248 <li>public void sendData<font color="#000000">(Object o);</font><br>
249This 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>
250</ul>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]251
252
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]253<h1><a name="EventAdminHandlers-HandlerArchitecture"></a>Handler Architecture</h1>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]254
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]255<p>Here is shown the global architecture of the EventHandler : the
256interactions between the user components (i.e., POJO), the handler and
257the OSGi runtime environment.</p>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]258
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]259<p><img src="event-admin-handlers_files/handler-arch.png" align="absmiddle" border="0"></p>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]260
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]261<h1><a name="EventAdminHandlers-EventHandlerFeatures"></a>EventHandler Features</h1>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]262
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]263<p>In this section, you will find some examples of the handler's features.</p>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]264
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]265<h2><a name="EventAdminHandlers-Instancecustomization"></a>Instance customization</h2>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]266
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]267<p>As described in the 'Instance configuration' section, you can
268(re)define some of the subscribers or publishers attributes. You can
269notice that required attributes that are not defined in the component
270description must be defined in the instance configuration section.
271Hereafter is an example of an instance configuration of this handler :</p>
272<div class="code"><div class="codeContent">
273<pre class="code-xml">&lt;ipojo
274 <span class="code-keyword">xmlns:ev</span>=<span class="code-quote">"org.apache.felix.ipojo.handlers.event.EventAdminHandler"</span>&gt;
275 <span class="code-tag">&lt;component className=<span class="code-quote">"...MyComponent"</span>&gt;</span>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]276 &lt;ev:subscriber
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]277 name=<span class="code-quote">"mySubscriber"</span>
278 callback=<span class="code-quote">"handleEvent"</span>/&gt;
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]279 &lt;ev:publisher
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]280 name=<span class="code-quote">"myPublisher"</span>
281 field=<span class="code-quote">"m_publisher"</span>/&gt;
282 <span class="code-tag">&lt;/component&gt;</span>
283 <span class="code-tag">&lt;instance component=<span class="code-quote">"...MyComponent"</span>&gt;</span>
284 <span class="code-tag">&lt;property name=<span class="code-quote">"event.topics"</span>&gt;</span>
285 <span class="code-tag">&lt;property name=<span class="code-quote">"mySubscriber"</span> value=<span class="code-quote">"foo"</span>/&gt;</span>
286 <span class="code-tag">&lt;property name=<span class="code-quote">"myPublisher"</span> value=<span class="code-quote">"bar,nuts"</span>/&gt;</span>
287 <span class="code-tag">&lt;/property&gt;</span>
288 <span class="code-tag">&lt;property name=<span class="code-quote">"event.filter"</span>&gt;</span>
289 &lt;property name=<span class="code-quote">"mySubscriber"</span>
290 value=<span class="code-quote">"|((arg=Minibar)(arg=Coconuts))"</span>/&gt;
291 <span class="code-tag">&lt;/property&gt;</span>
292 <span class="code-tag">&lt;/instance&gt;</span>
293<span class="code-tag">&lt;/ipojo&gt;</span></pre>
294</div></div>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]295
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]296<h2><a name="EventAdminHandlers-Dataevents"></a>Data events</h2>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]297
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]298<p>One of the most important features of the EventHandler is the
299capability of sending and receiving data events. You may know that the
300OSGi EventAdmin Service allows bundles to send custom objects in
301events, inserting them in the event's dictionary. The EventHandler
302hides the dictionary manipulation and allows iPOJO components to
303receive custom objects at any time.</p>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]304
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]305<p>First, you have define the <em>data-key</em> attribute in the
306publisher configuration. Sent objects will be contained in the event
307dictionary and are accessible with the "user.data" key.</p>
308<div class="code"><div class="codeContent">
309<pre class="code-xml">&lt;ipojo
310 <span class="code-keyword">xmlns:ev</span>=<span class="code-quote">"org.apache.felix.ipojo.handlers.event.EventAdminHandler"</span>&gt;
311 <span class="code-tag">&lt;component className=<span class="code-quote">"...DataPublisher"</span>&gt;</span>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]312 &lt;ev:publisher
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]313 name=<span class="code-quote">"myPublisher"</span>
314 field=<span class="code-quote">"m_publisher"</span>
315 topics=<span class="code-quote">"myTopic"</span>
316 data-key=<span class="code-quote">"my.data"</span>/&gt;
317 <span class="code-tag">&lt;/component&gt;</span>
318 <span class="code-tag">&lt;instance component=<span class="code-quote">"...DataPublisher"</span>/&gt;</span>
319<span class="code-tag">&lt;/ipojo&gt;</span></pre>
320</div></div>
321<p>Then you can use the <em>sendData</em> method of your configured publisher.</p>
322<div class="code"><div class="codeContent">
323<pre class="code-java"><span class="code-keyword">import</span> org.apache.felix.ipojo.handlers.event.publisher.Publisher;
324<span class="code-comment">//...
325</span><span class="code-keyword">public</span> class DataPublisher ... {
326 <span class="code-keyword">private</span> Publisher m_publisher;
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]327
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]328 <span class="code-keyword">public</span> void doSomething() {
329 <span class="code-comment">// MyFavoriteType <span class="code-keyword">extends</span> MyFavoriteInterface
330</span> MyFavoriteType data = <span class="code-keyword">new</span> MyFavoriteType(...);
331 <span class="code-comment">//...
332</span> <span class="code-comment">// Send a data event
333</span> m_publisher.sendData(data);
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]334 }
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]335}</pre>
336</div></div>
337<p>The second step is to configure an event subscriber to receive such events. The <em>data-key</em> attribute's value of the subscriber must be the same than the publisher's one. The <em>data-type</em>describe
338the type of received data events, and thus, must be compatible with the
339sent object's type (i.e., super-class or inherited interface). Then you
340can finally receive the sent object in the callback method. The
341parameter type of the callback must be the same than the data-type
342attribute value.</p>
343<div class="code"><div class="codeContent">
344<pre class="code-xml">&lt;ipojo
345 <span class="code-keyword">xmlns:ev</span>=<span class="code-quote">"org.apache.felix.ipojo.handlers.event.EventAdminHandler"</span>&gt;
346 <span class="code-tag">&lt;component className=<span class="code-quote">"...DataEventSubscriber"</span>&gt;</span>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]347 &lt;ev:subscriber
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]348 name=<span class="code-quote">"mySubscriber"</span>
349 callback=<span class="code-quote">"handleData"</span>
350 topics=<span class="code-quote">"myTopic"</span>
351 data-key=<span class="code-quote">"my.data"</span>
352 data-type=<span class="code-quote">"my.package.MyFavoriteInterface"</span>/&gt;
353 <span class="code-tag">&lt;/component&gt;</span>
354 <span class="code-tag">&lt;instance component=<span class="code-quote">"...DataEventSubscriber"</span>/&gt;</span>
355<span class="code-tag">&lt;/ipojo&gt;</span></pre>
356</div></div>
357<div class="code"><div class="codeContent">
358<pre class="code-java"><span class="code-keyword">import</span> my.<span class="code-keyword">package</span>.MyFavoriteInterface;
359<span class="code-comment">//...
360</span><span class="code-keyword">public</span> class DataEventSubscriber ... {
361 <span class="code-keyword">public</span> void handleData(MyFavoriteInterface o) {
362 <span class="code-comment">// <span class="code-object">Object</span> received
363</span> <span class="code-comment">//...
364</span> }
365}</pre>
366</div></div>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]367
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]368<h2><a name="EventAdminHandlers-Noteonsynchronouseventsending"></a>Note on synchronous event sending</h2>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]369
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]370<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>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]371
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]372<p>The behaviour of synchronous event sending is particular when you
373specify several topics in the publisher description. The event is
374synchronously sent to each topic, one by one. So when you return from
375this function, you can be sure that the event has been delivered to
376each topic.</p>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]377
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]378<h2><a name="EventAdminHandlers-Publisherinstanceinformation"></a>Publisher instance information</h2>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]379
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]380<p>All events sent by a publisher contains the name of the component
381instance that sent them. Its enables to filter received events
382depending the sender instance. The instance name is accessible in the
383event 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>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]384
385
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]386<h2><a name="EventAdminHandlers-Configuringthehandlerwithannotations\Newin1.1.0SNAPSHOT\"></a>Configuring the handler with annotations [New in 1.1.0-SNAPSHOT]</h2>
387
388<p>It is possible to configure the handler with a simple annotations
389available in the annotation pack ('annotation' project in the iPOJO
390trunk). Here is an example of usage:</p>
391<div class="code"><div class="codeContent">
392<pre class="code-java"><span class="code-keyword">import</span> org.apache.felix.ipojo.annotations.Component;
393<span class="code-keyword">import</span> org.apache.felix.ipojo.handlers.event.Subscriber;
394<span class="code-keyword">import</span> org.osgi.service.event.Event;
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]395
396
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]397@Component
398<span class="code-keyword">public</span> class PubSub {
399 @org.apache.felix.ipojo.handlers.event.Publisher(name=<span class="code-quote">"p1"</span>, synchronous=<span class="code-keyword">true</span>)
400 org.apache.felix.ipojo.handlers.event.publisher.Publisher publisher1;
401
402 @org.apache.felix.ipojo.handlers.event.Publisher(name=<span class="code-quote">"p2"</span>, synchronous=<span class="code-keyword">false</span>, topics=<span class="code-quote">"foo,bar"</span>, data_key=<span class="code-quote">"data"</span>)
403 org.apache.felix.ipojo.handlers.event.publisher.Publisher publisher2;
404
405 @org.apache.felix.ipojo.handlers.event.Publisher(name=<span class="code-quote">"p3"</span>, synchronous=<span class="code-keyword">true</span>, topics=<span class="code-quote">"bar"</span>)
406 org.apache.felix.ipojo.handlers.event.publisher.Publisher publisher3;
407
408 @Subscriber(name=<span class="code-quote">"s1"</span>, data_key=<span class="code-quote">"data"</span>)
409 <span class="code-keyword">public</span> void receive1(<span class="code-object">Object</span> foo) {
410 <span class="code-comment">// <span class="code-object">Process</span> event
411</span> }
412
413 @Subscriber(name=<span class="code-quote">"s2"</span>, topics=<span class="code-quote">"foo,bar"</span>, filter=<span class="code-quote">"(foo=<span class="code-keyword">true</span>)"</span>)
414 <span class="code-keyword">public</span> void receive2(Event foo) {
415 <span class="code-comment">// <span class="code-object">Process</span> event
416</span> }
417
418
419 @Subscriber(name=<span class="code-quote">"s3"</span>, topics=<span class="code-quote">"foo"</span>, data_key=<span class="code-quote">"data"</span>, data_type=<span class="code-quote">"java.lang.<span class="code-object">String</span>"</span>)
420 <span class="code-keyword">public</span> void receive3(<span class="code-object">String</span> foo) {
421 <span class="code-comment">// <span class="code-object">Process</span> event
422</span> }
423}</pre>
424</div></div></td>
425<td class="confluenceTd" valign="top" width="20%">
426<h6><a name="EventAdminHandlers-Overview"></a><b>Overview</b></h6>
427<ul>
428 <li><a href="http://felix.apache.org/site/apache-felix-ipojo.html" title="Apache Felix iPOJO">Home Page</a></li>
429 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-feature-overview.html" title="Apache Felix iPOJO Feature Overview">iPOJO Feature Overview</a></li>
430 <li><a href="http://felix.apache.org/site/download.html" title="Download">Download &amp; Install </a></li>
431</ul>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]432
433
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]434<h6><a name="EventAdminHandlers-GettingStarted"></a><b>Getting Started</b></h6>
435<ul>
436 <li><a href="http://felix.apache.org/site/ipojo-in-10-minutes.html" title="iPOJO in 10 minutes">iPOJO in 10 minutes</a></li>
437 <li><a href="http://felix.apache.org/site/how-to-use-ipojo-annotations.html" title="How to use iPOJO Annotations">How to use iPOJO Annotations</a></li>
438 <li><a href="http://felix.apache.org/site/ipojo-hello-word-maven-based-tutorial.html" title="iPOJO Hello Word (Maven-Based) tutorial">iPOJO Hello Word (Maven-Based) tutorial</a></li>
439 <li><a href="http://felix.apache.org/site/ipojo-advanced-tutorial.html" title="iPOJO Advanced Tutorial">iPOJO Advanced Tutorial</a></li>
440 <li><a href="http://felix.apache.org/site/ipojo-composition-tutorial.html" title="iPOJO Composition Tutorial">iPOJO Composition Tutorial</a></li>
441</ul>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]442
443
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]444<h6><a name="EventAdminHandlers-UserGuide"></a><b>User Guide</b></h6>
445<ul>
446 <li><a href="http://felix.apache.org/site/describing-components.html" title="Describing components">Describing components (handler list) </a></li>
447 <li><a href="http://felix.apache.org/site/using-xml-schemas.html" title="Using XML Schemas">Using XML Schemas</a></li>
448 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-testing-components.html" title="apache-felix-ipojo-testing-components">Testing components</a></li>
449 <li><a href="http://felix.apache.org/site/ipojo-advanced-topics.html" title="iPOJO Advanced Topics">Advanced Topics</a></li>
450 <li><a href="http://felix.apache.org/site/ipojo-faq.html" title="iPOJO FAQ">FAQ</a></li>
451 <li><a href="http://felix.apache.org/site/ipojo-reference-card.html" title="iPOJO-Reference-Card">iPOJO Reference Card</a></li>
452</ul>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]453
454
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]455<h6><a name="EventAdminHandlers-Tools"></a><b>Tools</b></h6>
456<ul>
457 <li><a href="http://felix.apache.org/site/ipojo-eclipse-plug-in.html" title="iPOJO Eclipse Plug-in">iPOJO Eclipse Plug-in</a></li>
458 <li><a href="http://felix.apache.org/site/ipojo-ant-task.html" title="iPOJO Ant Task">iPOJO Ant Task</a></li>
459 <li><a href="http://felix.apache.org/site/ipojo-maven-plug-in.html" title="iPOJO Maven Plug-in">iPOJO Maven Plug-in</a></li>
460 <li><a href="http://felix.apache.org/site/ipojo-arch-command.html" title="iPOJO-Arch-Command">iPOJO Arch Command</a></li>
461 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-junit4osgi.html" title="apache-felix-ipojo-junit4osgi">Junit4OSGi</a></li>
462 <li><a href="http://felix.apache.org/site/ipojo-concepts-overview.html" title="iPOJO Concepts Overview">iPOJO concepts overview</a></li>
463</ul>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]464
465
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]466<h6><a name="EventAdminHandlers-DeveloperGuide"></a><b>Developer Guide</b></h6>
467<ul>
468 <li>API: <span class="nobr"><a href="http://people.apache.org/%7Eclement/ipojo/api/1.0/" title="Visit page outside Confluence" rel="nofollow">1.0<sup><img class="rendericon" src="event-admin-handlers_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
469 <li><a href="http://felix.apache.org/site/how-to-write-your-own-handler.html" title="How to write your own handler">How to write your own handler</a></li>
470 <li><a href="http://felix.apache.org/site/how-to-use-ipojo-manipulation-metadata.html" title="How to use iPOJO Manipulation Metadata">How to use iPOJO Manipulation Metadata</a></li>
471 <li><a href="http://felix.apache.org/site/dive-into-the-ipojo-manipulation-depths.html" title="Dive into the iPOJO Manipulation depths">Dive into the iPOJO Manipulation depths</a></li>
472</ul>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]473
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]474
475<h6><a name="EventAdminHandlers-Misc&amp;Contact"></a><b>Misc &amp; Contact</b></h6>
476<ul>
477 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-issuestracker.html" title="apache-felix-ipojo-issuestracker">Issues Tracker</a></li>
478 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-supportedvms.html" title="apache-felix-ipojo-supportedVMs">Supported JVMs</a></li>
479 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-supportedosgi.html" title="apache-felix-ipojo-supportedOSGi">Supported OSGi Implementations</a></li>
480 <li><span class="nobr"><a href="http://ipojo-dark-side.blogspot.com/" title="Visit page outside Confluence" rel="nofollow">iPOJO's Dark Side Blog<sup><img class="rendericon" src="event-admin-handlers_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
481 <li><a href="http://felix.apache.org/site/future-ideas.html" title="Future Ideas">Future Ideas</a></li>
482 <li><a href="http://felix.apache.org/site/contact.html" title="Contact">Contact</a></li>
483 <li><a href="http://felix.apache.org/site/related-works.html" title="Related Works">Related Works</a></li>
484 <li><a href="http://felix.apache.org/site/article-presentations.html" title="Article &amp; Presentations">Article &amp; Presentations</a></li>
485</ul>
486
487
488<hr>
489<div class="" align="center">
490<p><span class="nobr"><a href="http://cwiki.apache.org/confluence/createrssfeed.action?types=blogpost&amp;statuses=created&amp;statuses=modified&amp;spaces=FELIX&amp;labelString=iPOJO&amp;rssType=atom&amp;maxResults=10&amp;timeSpan=5&amp;publicFeed=true&amp;title=iPOJO%20Atom%20Feed" title="Stay tuned!" rel="nofollow"><img src="event-admin-handlers_files/feed-icon-32x32.png" align="absmiddle" border="0"><sup><img class="rendericon" src="event-admin-handlers_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></p></div>
491
492<script type="text/javascript">
493var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
494document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
495</script><script src="event-admin-handlers_files/ga.js" type="text/javascript"></script>
496<script type="text/javascript">
497var pageTracker = _gat._getTracker("UA-1518442-4");
498pageTracker._trackPageview();
499</script>
500</td></tr></tbody></table>
501 </div>
502 </body></html>