Blame - ipojo/handler/eventadmin/doc/event-admin-handlers.html - onos-felix

<LI><SPAN class="nobr"><A href="downloads.html" title="Visit page outside Confluence" rel="nofollow">downloads<SUP><IMG class="rendericon" src="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>

18

<LI><A href="documentation.html" title="documentation">documentation</A></LI>

19

<LI><A href="mailinglists.html" title="mailinglists">mailing lists</A></LI>

20

<LI><A href="contributing.html" title="Contributing">contributing</A></LI>

21

22

<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="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>

23

<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="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN>

24

25

26

27

</LI>

</UL>

</DIV>

<H1><A name="EventAdminHandlers-EventAdminHandlers"></A>Event Admin Handlers</H1>

35

36

<P>The goal of the Event Admin Handlers is to allow event communications between iPOJO component instances. The implementation of these handlers relies on an event admin services. It enables the iPOJO component to listen to a list of topics and to receive all related event. It also allows components to send events in an easy way.</P>

37

38

<P>Hereafter is presented a small example of the metadata.xml file :</P>

39

40

<PRE class="code-xml"><ipojo

41

<SPAN class="code-keyword">xmlns:ev</SPAN>=<SPAN class="code-quote">"org.apache.felix.ipojo.handlers.event.EventAdminHandler"</SPAN>>

42

<SPAN class="code-tag"><component className=<SPAN class="code-quote">"...MyComponent"</SPAN>></SPAN>

43

<ev:subscriber

44

name=<SPAN class="code-quote">"mySubscriber"</SPAN>

45

callback=<SPAN class="code-quote">"receive"</SPAN>

46

topics=<SPAN class="code-quote">"foo"</SPAN>/>

47

<ev:publisher

48

name=<SPAN class="code-quote">"myPublisher"</SPAN>

49

field=<SPAN class="code-quote">"m_publisher"</SPAN>

50

topics=<SPAN class="code-quote">"bar,nuts"</SPAN>/>

51

52

<SPAN class="code-tag"><instance component=<SPAN class="code-quote">"...MyComponent"</SPAN>/></SPAN>

53

54

</DIV></DIV>

55

<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>

56

57

<P>Here is an example of the component implementation, compatible with the given description :</P>

58

59

<PRE class="code-java"><SPAN class="code-keyword">import</SPAN> org.apache.felix.ipojo.handlers.event.publisher.Publisher;

60

<SPAN class="code-keyword">import</SPAN> org.osgi.service.event.Event;

61

62

<SPAN class="code-keyword">public</SPAN> class MyComponent ... {

63

<SPAN class="code-keyword">private</SPAN> Publisher m_publisher;

64

<SPAN class="code-keyword">public</SPAN> void receive(Event e) {

65

<SPAN class="code-comment">// Event received

66

</SPAN> <SPAN class="code-comment">// Do something with the event}

67

</SPAN>

68

<SPAN class="code-keyword">public</SPAN> void doSomething() {

69

Dictionary e = <SPAN class="code-keyword">new</SPAN> Properties();

70

<SPAN class="code-comment">//...

71

</SPAN> <SPAN class="code-comment">// Fill out the event

72

</SPAN>

73

<SPAN class="code-comment">// Send event

74

</SPAN> m_publisher.send(e);

}

}</PRE>

</DIV></DIV>

<H1><A name="EventAdminHandlers-Download"></A>Download</H1>

80

81

<P>The event admin handlers (to send and receive events) are available in the Felix trunk in the iPOJO project. See the <A href="download.html" title="Download">Download</A> page to download and compile these sources.</P>

<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>

86

87

<H1><A name="EventAdminHandlers-EventHandlerSpecification"></A>EventHandler Specification</H1>

88

89

<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>

90

91

<P>Handler namespace : org.apache.felix.ipojo.handlers.event.EventAdminHandler</P>

92

93

<H2><A name="EventAdminHandlers-Eventsubscriberattributes"></A>Event subscriber attributes</H2>

<TR>

<TH class="confluenceTh"> Attribute name </TH>

98

<TH class="confluenceTh"> Required </TH>

99

<TH class="confluenceTh"> Description </TH>

</TR>

<TR>

<TD class="confluenceTd"> The name of the event subscriber, acting as a unique identifier. </TD>

105

</TR>

106

<TR>

107

<TD class="confluenceTd"> <EM>callback</EM> </TD>

108

109

<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>

110

</TR>

111

<TR>

112

<TD class="confluenceTd"> <EM>topics</EM> </TD>

113

114

<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"> 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">

120

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">

121

This attribute is generally used with the <EM>data-type</EM>attribute to specify the received object type. <BR clear="all">

122

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"> 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">

128

Data events that are not corresponding to the specified type will be ignored (with a warning message). </TD>

129

</TR>

130

<TR>

131

<TD class="confluenceTd"> <EM>filter</EM> </TD>

132

133

<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>

134

</TR>

135

</TBODY></TABLE>

136

<P>* These attributes can be (re)defined in the instance configuration.</P>

137

138

<H2><A name="EventAdminHandlers-Eventpublisherattributes"></A>Event publisher attributes</H2>

<TR>

<TH class="confluenceTh"> Attribute name </TH>

143

<TH class="confluenceTh"> Required </TH>

144

<TH class="confluenceTh"> Description </TH>

</TR>

<TR>

<TD class="confluenceTd"> The name of the event publisher, acting as a unique identifier. </TD>

150

</TR>

151

<TR>

152

<TD class="confluenceTd"> <EM>field</EM> </TD>

153

154

<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>

155

</TR>

156

<TR>

157

<TD class="confluenceTd"> <EM>topics</EM> </TD>

158

159

<TD class="confluenceTd"> The comma-separated-list of the topics on which events will be sent. All subscribers that are listening to one of these topics will receive the events. </TD>

</TR>

<TR>

<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">

165

The default value of this attribute is user.data. </TD>

166

</TR>

167

<TR>

168

<TD class="confluenceTd"> <EM>synchronous</EM> </TD>

169

170

<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">

171

The default value of this attribute is "false". </TD>

172

</TR>

173

</TBODY></TABLE>

174

<P>* These attributes can be (re)defined in the instance configuration.</P>

175

176

<H2><A name="EventAdminHandlers-Instanceconfiguration"></A>Instance configuration</H2>

177

178

<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>

179

<UL>

180

<LI><EM>event.topics</EM> : overrides <EM>topics</EM> attribute, available for both subscribers and publishers configuration</LI>

181

<LI><EM>event.filter</EM> : overrides <EM>filter</EM> attribute, available for subscribers configuration only.</LI>

</UL>

<H2><A name="EventAdminHandlers-Publisherinterface"></A>Publisher interface</H2>

186

187

<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>

188

<UL>

189

<LI>public void send<FONT color="#000000">(Dictionary content);</FONT><BR>

190

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>

191

<LI>public void sendData<FONT color="#000000">(Object o);</FONT><BR>

192

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>

<H1><A name="EventAdminHandlers-HandlerArchitecture"></A>Handler Architecture</H1>

197

198

<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>

<H1><A name="EventAdminHandlers-EventHandlerFeatures"></A>EventHandler Features</H1>

203

204

<P>In this section, you will find some examples of the handler's features.</P>

205

206

<H2><A name="EventAdminHandlers-Instancecustomization"></A>Instance customization</H2>

207

208

<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>

209

210

<PRE class="code-xml"><ipojo

211

<SPAN class="code-keyword">xmlns:ev</SPAN>=<SPAN class="code-quote">"org.apache.felix.ipojo.handlers.event.EventAdminHandler"</SPAN>>

212

<SPAN class="code-tag"><component className=<SPAN class="code-quote">"...MyComponent"</SPAN>></SPAN>

213

<ev:subscriber

214

name=<SPAN class="code-quote">"mySubscriber"</SPAN>

215

callback=<SPAN class="code-quote">"handleEvent"</SPAN>/>

216

<ev:publisher

217

name=<SPAN class="code-quote">"myPublisher"</SPAN>

218

field=<SPAN class="code-quote">"m_publisher"</SPAN>/>

219

220

<SPAN class="code-tag"><instance component=<SPAN class="code-quote">"...MyComponent"</SPAN>></SPAN>

221

<SPAN class="code-tag"><property name=<SPAN class="code-quote">"event.topics"</SPAN>></SPAN>

222

<SPAN class="code-tag"><property name=<SPAN class="code-quote">"mySubscriber"</SPAN> value=<SPAN class="code-quote">"foo"</SPAN>/></SPAN>

223

<SPAN class="code-tag"><property name=<SPAN class="code-quote">"myPublisher"</SPAN> value=<SPAN class="code-quote">"bar,nuts"</SPAN>/></SPAN>

224

225

<SPAN class="code-tag"><property name=<SPAN class="code-quote">"event.filter"</SPAN>></SPAN>

226

<property name=<SPAN class="code-quote">"mySubscriber"</SPAN>

227

value=<SPAN class="code-quote">"|((arg=Minibar)(arg=Coconuts))"</SPAN>/>

</DIV></DIV>

<H2><A name="EventAdminHandlers-Dataevents"></A>Data events</H2>

234

235

<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>

236

237

<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>

238

239

<PRE class="code-xml"><ipojo

240

<SPAN class="code-keyword">xmlns:ev</SPAN>=<SPAN class="code-quote">"org.apache.felix.ipojo.handlers.event.EventAdminHandler"</SPAN>>

241

<SPAN class="code-tag"><component className=<SPAN class="code-quote">"...DataPublisher"</SPAN>></SPAN>

242

<ev:publisher

243

name=<SPAN class="code-quote">"myPublisher"</SPAN>

244

field=<SPAN class="code-quote">"m_publisher"</SPAN>

245

topics=<SPAN class="code-quote">"myTopic"</SPAN>

246

data-key=<SPAN class="code-quote">"my.data"</SPAN>/>

247

248

<SPAN class="code-tag"><instance component=<SPAN class="code-quote">"...DataPublisher"</SPAN>/></SPAN>

249

250

</DIV></DIV>

251

<P>Then you can use the <EM>sendData</EM> method of your configured publisher.</P>

252

253

<PRE class="code-java"><SPAN class="code-keyword">import</SPAN> org.apache.felix.ipojo.handlers.event.publisher.Publisher;

254

<SPAN class="code-comment">//...

255

</SPAN><SPAN class="code-keyword">public</SPAN> class DataPublisher ... {

256

<SPAN class="code-keyword">private</SPAN> Publisher m_publisher;

257

258

<SPAN class="code-keyword">public</SPAN> void doSomething() {

259

<SPAN class="code-comment">// MyFavoriteType <SPAN class="code-keyword">extends</SPAN> MyFavoriteInterface

260

</SPAN> MyFavoriteType data = <SPAN class="code-keyword">new</SPAN> MyFavoriteType(...);

261

<SPAN class="code-comment">//...

262

</SPAN> <SPAN class="code-comment">// Send a data event

263

</SPAN> m_publisher.sendData(data);

}

}</PRE>

</DIV></DIV>

<P>The second step is to configure an event subscriber to receive such events. The <EM>data-key</EM> attribute's value of the subscriber must be the same than the publisher's one. The <EM>data-type</EM>describe the type of received data events, and thus, must be compatible with the sent object's type (i.e., super-class or inherited interface). Then you can finally receive the sent object in the callback method. The parameter type of the callback must be the same than the data-type attribute value.</P>

268

269

<PRE class="code-xml"><ipojo

270

<SPAN class="code-keyword">xmlns:ev</SPAN>=<SPAN class="code-quote">"org.apache.felix.ipojo.handlers.event.EventAdminHandler"</SPAN>>

271

<SPAN class="code-tag"><component className=<SPAN class="code-quote">"...DataEventSubscriber"</SPAN>></SPAN>

272

<ev:subscriber

273

name=<SPAN class="code-quote">"mySubscriber"</SPAN>

274

callback=<SPAN class="code-quote">"handleData"</SPAN>

275

topics=<SPAN class="code-quote">"myTopic"</SPAN>

276

data-key=<SPAN class="code-quote">"my.data"</SPAN>

277

data-type=<SPAN class="code-quote">"my.package.MyFavoriteInterface"</SPAN>/>

278

279

<SPAN class="code-tag"><instance component=<SPAN class="code-quote">"...DataEventSubscriber"</SPAN>/></SPAN>

</DIV></DIV>

<PRE class="code-java"><SPAN class="code-keyword">import</SPAN> my.<SPAN class="code-keyword">package</SPAN>.MyFavoriteInterface;

284

<SPAN class="code-comment">//...

285

</SPAN><SPAN class="code-keyword">public</SPAN> class DataEventSubscriber ... {

286

<SPAN class="code-keyword">public</SPAN> void handleData(MyFavoriteInterface o) {

287

<SPAN class="code-comment">// <SPAN class="code-object">Object</SPAN> received

288

</SPAN> <SPAN class="code-comment">//...

</SPAN> }

}</PRE>

</DIV></DIV>

<H2><A name="EventAdminHandlers-Noteonsynchronouseventsending"></A>Note on synchronous event sending</H2>

294

295

<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>

296

297

<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>

298

299

<H2><A name="EventAdminHandlers-Publisherinstanceinformation"></A>Publisher instance information</H2>

300

301

<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></TD>

302

303

<H6><A name="EventAdminHandlers-Overview"></A><B>Overview</B></H6>

304

<UL>

305

306

<LI><A href="apache-felix-ipojo-feature-overview.html" title="Apache Felix iPOJO Feature Overview">iPOJO Feature Overview</A></LI>

307

<LI><A href="download.html" title="Download">Download & Install </A></LI>

</UL>

<H6><A name="EventAdminHandlers-GettingStarted"></A><B>Getting Started</B></H6>

312

<UL>

313

<LI><A href="ipojo-in-10-minutes.html" title="iPOJO in 10 minutes">iPOJO in 10 minutes</A></LI>

314

<LI><A href="ipojo-hello-word-maven-based-tutorial.html" title="iPOJO Hello Word (Maven-Based) tutorial">iPOJO Hello Word (Maven-Based) tutorial</A></LI>

315

<LI><A href="ipojo-advanced-tutorial.html" title="iPOJO Advanced Tutorial">iPOJO Advanced Tutorial</A></LI>

</UL>

<H6><A name="EventAdminHandlers-UserGuide"></A><B>User Guide</B></H6>

320

<UL>

321

<LI><A href="describing-components.html" title="Describing components">Describing components (handler list) </A></LI>

322

<LI><A href="how-to-use-ipojo-annotations.html" title="How to use iPOJO Annotations">How to use iPOJO Annotations</A></LI>

323

<LI><A href="using-xml-schemas.html" title="Using XML Schemas">Using XML Schemas</A></LI>

324

<LI><A href="ipojo-advanced-topics.html" title="iPOJO Advanced Topics">Advanced Topics</A></LI>

</UL>

<H6><A name="EventAdminHandlers-Tools"></A><B>Tools</B></H6>

330

<UL>

331

<LI><A href="ipojo-eclipse-plug-in.html" title="iPOJO Eclipse Plug-in">iPOJO Eclipse Plug-in</A></LI>

332

<LI><A href="ipojo-ant-task.html" title="iPOJO Ant Task">iPOJO Ant Task</A></LI>

333

<LI><A href="ipojo-maven-plug-in.html" title="iPOJO Maven Plug-in">iPOJO Maven Plug-in</A></LI>

334

<LI><A href="ipojo-concepts-overview.html" title="iPOJO Concepts Overview">iPOJO concepts overview</A></LI>

</UL>

<H6><A name="EventAdminHandlers-DeveloperGuide"></A><B>Developer Guide</B></H6>

339

<UL>

340

341

<LI><A href="how-to-write-your-own-handler.html" title="How to write your own handler">How to write your own handler</A></LI>

342

<LI><A href="how-to-use-ipojo-manipulation-metadata.html" title="How to use iPOJO Manipulation Metadata">How to use iPOJO Manipulation Metadata</A></LI>

</UL>

<H6><A name="EventAdminHandlers-Misc%26Contact"></A><B>Misc & Contact</B></H6>

347

<UL>

348

<LI><A href="apache-felix-ipojo-issuestracker.html" title="apache-felix-ipojo-issuestracker">Issues Tracker</A></LI>

349

<LI><A href="apache-felix-ipojo-supportedvms.html" title="apache-felix-ipojo-supportedVMs">Supported JVMs</A></LI>