copland 0.8.0 → 1.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (50) hide show
  1. data/doc/manual-html/chapter-1.html +227 -36
  2. data/doc/manual-html/chapter-10.html +155 -82
  3. data/doc/manual-html/chapter-11.html +90 -267
  4. data/doc/manual-html/chapter-12.html +289 -71
  5. data/doc/manual-html/chapter-13.html +430 -0
  6. data/doc/manual-html/chapter-2.html +45 -21
  7. data/doc/manual-html/chapter-3.html +45 -21
  8. data/doc/manual-html/chapter-4.html +45 -21
  9. data/doc/manual-html/chapter-5.html +45 -21
  10. data/doc/manual-html/chapter-6.html +49 -21
  11. data/doc/manual-html/chapter-7.html +45 -21
  12. data/doc/manual-html/chapter-8.html +66 -26
  13. data/doc/manual-html/chapter-9.html +48 -24
  14. data/doc/manual-html/index.html +54 -22
  15. data/doc/manual-html/manual.css +12 -0
  16. data/doc/manual-html/tutorial-1.html +45 -21
  17. data/doc/manual-html/tutorial-2.html +45 -21
  18. data/doc/manual-html/tutorial-3.html +45 -21
  19. data/doc/manual-html/tutorial-4.html +45 -21
  20. data/doc/manual-html/tutorial-5.html +45 -21
  21. data/doc/manual/manual.css +12 -0
  22. data/doc/manual/manual.rb +1 -1
  23. data/doc/manual/manual.yml +426 -20
  24. data/doc/packages/copland.html +41 -9
  25. data/doc/packages/copland.lib.html +36 -8
  26. data/doc/packages/copland.remote.html +46 -10
  27. data/doc/packages/copland.webrick.html +16 -65
  28. data/doc/packages/index.html +1 -1
  29. data/doc/presentation/copland.mgp +1083 -0
  30. data/doc/presentation/to_html.rb +52 -0
  31. data/lib/copland/configuration-point/common.rb +32 -1
  32. data/lib/copland/configuration/yaml/service-point.rb +10 -1
  33. data/lib/copland/log-factory.rb +28 -12
  34. data/lib/copland/logger.rb +155 -0
  35. data/lib/copland/models/singleton.rb +8 -2
  36. data/lib/copland/package.rb +32 -14
  37. data/lib/copland/service-point.rb +7 -0
  38. data/lib/copland/thread.rb +104 -0
  39. data/lib/copland/utils.rb +10 -3
  40. data/lib/copland/version.rb +2 -2
  41. data/test/configuration/yaml/tc_service-point-processor.rb +8 -0
  42. data/test/custom-logger.yml +2 -1
  43. data/test/impl/tc_logging-interceptor.rb +12 -12
  44. data/test/logger.yml +1 -1
  45. data/test/mock.rb +2 -0
  46. data/test/tc_logger.rb +19 -6
  47. data/test/tc_package.rb +25 -0
  48. data/test/tc_queryable-mutex.rb +75 -0
  49. data/test/tc_registry.rb +8 -4
  50. metadata +9 -2
@@ -0,0 +1,430 @@
1
+ <html>
2
+ <head>
3
+ <title>Copland Manual :: Chapter 13: Listeners and Event Producers</title>
4
+ <link type="text/css" rel="stylesheet" href="manual.css" />
5
+ </head>
6
+
7
+ <body>
8
+ <div id="banner">
9
+ <table border='0' cellpadding='0' cellspacing='0' width='100%'>
10
+ <tr><td valign='top' align='left'>
11
+ <div class="title">
12
+ <span class="product">Copland&mdash;</span><br />
13
+ <span class="tagline">compose yourself...</span>
14
+ </div>
15
+ </td><td valign='middle' align='right'>
16
+ <div class="info">
17
+ Copland Version: <strong>1.0.0</strong><br />
18
+ Manual Last Updated: <strong>2004-10-12 02:22 GMT</strong>
19
+ </div>
20
+ </td></tr>
21
+ </table>
22
+ </div>
23
+
24
+ <table border='0' width='100%' cellpadding='0' cellspacing='0'>
25
+ <tr><td valign='top'>
26
+
27
+ <div id="navigation">
28
+ <h1>Copland Manual</h1>
29
+
30
+ <h2>Chapters</h2>
31
+ <ol type="I">
32
+
33
+ <li>
34
+ <a href="chapter-1.html">
35
+ Introduction
36
+ </a>
37
+
38
+ <ol type="1">
39
+
40
+ <li><a href="chapter-1.html#s1">What is Copland?</a></li>
41
+
42
+ <li><a href="chapter-1.html#s2">What Can Copland Do For Me?</a></li>
43
+
44
+ <li><a href="chapter-1.html#s3">Copland <em>sans</em> Buzzwords</a></li>
45
+
46
+ <li><a href="chapter-1.html#s4">Copland <em>avec</em> Buzzwords</a></li>
47
+
48
+ <li><a href="chapter-1.html#s5">The Buzzwords Themselves</a></li>
49
+
50
+ <li><a href="chapter-1.html#s6">Features</a></li>
51
+
52
+ <li><a href="chapter-1.html#s7">Getting Copland</a></li>
53
+
54
+ <li><a href="chapter-1.html#s8">License Information</a></li>
55
+
56
+ <li><a href="chapter-1.html#s9">Support</a></li>
57
+
58
+ </ol>
59
+ </li>
60
+
61
+ <li>
62
+ <a href="chapter-2.html">
63
+ Justification
64
+ </a>
65
+
66
+ <ol type="1">
67
+
68
+ <li><a href="chapter-2.html#s1">IoC in One Paragraph</a></li>
69
+
70
+ <li><a href="chapter-2.html#s2">Why IoC?</a></li>
71
+
72
+ <li><a href="chapter-2.html#s3">A Case Study</a></li>
73
+
74
+ </ol>
75
+ </li>
76
+
77
+ <li>
78
+ <a href="chapter-3.html">
79
+ Getting Started
80
+ </a>
81
+
82
+ <ol type="1">
83
+
84
+ <li><a href="chapter-3.html#s1">Terminology</a></li>
85
+
86
+ <li><a href="chapter-3.html#s2">Quickstart</a></li>
87
+
88
+ </ol>
89
+ </li>
90
+
91
+ <li>
92
+ <a href="chapter-4.html">
93
+ Copland's Design
94
+ </a>
95
+
96
+ <ol type="1">
97
+
98
+ <li><a href="chapter-4.html#s1">HiveMind</a></li>
99
+
100
+ <li><a href="chapter-4.html#s2">Registry Initialization</a></li>
101
+
102
+ <li><a href="chapter-4.html#s3">Service Instantiation</a></li>
103
+
104
+ <li><a href="chapter-4.html#s4">Interceptor Chains</a></li>
105
+
106
+ </ol>
107
+ </li>
108
+
109
+ <li>
110
+ <a href="chapter-5.html">
111
+ Packages
112
+ </a>
113
+
114
+ <ol type="1">
115
+
116
+ <li><a href="chapter-5.html#s1">Descriptor Syntax</a></li>
117
+
118
+ <li><a href="chapter-5.html#s2">Tips</a></li>
119
+
120
+ </ol>
121
+ </li>
122
+
123
+ <li>
124
+ <a href="chapter-6.html">
125
+ Service Points
126
+ </a>
127
+
128
+ <ol type="1">
129
+
130
+ <li><a href="chapter-6.html#s1">Descriptor Syntax</a></li>
131
+
132
+ </ol>
133
+ </li>
134
+
135
+ <li>
136
+ <a href="chapter-7.html">
137
+ Service Models
138
+ </a>
139
+
140
+ <ol type="1">
141
+
142
+ <li><a href="chapter-7.html#s1">Standard Models</a></li>
143
+
144
+ <li><a href="chapter-7.html#s2">Deferred Instantiation</a></li>
145
+
146
+ <li><a href="chapter-7.html#s3">Custom Service Models</a></li>
147
+
148
+ </ol>
149
+ </li>
150
+
151
+ <li>
152
+ <a href="chapter-8.html">
153
+ Configuration Points
154
+ </a>
155
+
156
+ <ol type="1">
157
+
158
+ <li><a href="chapter-8.html#s1">Descriptor Syntax</a></li>
159
+
160
+ <li><a href="chapter-8.html#s2">FactoryDefaults</a></li>
161
+
162
+ <li><a href="chapter-8.html#s3">ApplicationDefaults</a></li>
163
+
164
+ </ol>
165
+ </li>
166
+
167
+ <li>
168
+ <a href="chapter-9.html">
169
+ Contributions
170
+ </a>
171
+
172
+ <ol type="1">
173
+
174
+ </ol>
175
+ </li>
176
+
177
+ <li>
178
+ <a href="chapter-10.html">
179
+ Logging
180
+ </a>
181
+
182
+ <ol type="1">
183
+
184
+ <li><a href="chapter-10.html#s1">Log Factory</a></li>
185
+
186
+ <li><a href="chapter-10.html#s2">Configuration</a></li>
187
+
188
+ </ol>
189
+ </li>
190
+
191
+ <li>
192
+ <a href="chapter-11.html">
193
+ Service Factories
194
+ </a>
195
+
196
+ <ol type="1">
197
+
198
+ <li><a href="chapter-11.html#s1">Schemas</a></li>
199
+
200
+ <li><a href="chapter-11.html#s2">How do they work?</a></li>
201
+
202
+ <li><a href="chapter-11.html#s3">BuilderFactory</a></li>
203
+
204
+ </ol>
205
+ </li>
206
+
207
+ <li>
208
+ <a href="chapter-12.html">
209
+ Schemas
210
+ </a>
211
+
212
+ <ol type="1">
213
+
214
+ <li><a href="chapter-12.html#s1">Basic Format</a></li>
215
+
216
+ <li><a href="chapter-12.html#s2">Subschemas</a></li>
217
+
218
+ <li><a href="chapter-12.html#s3">Arrays</a></li>
219
+
220
+ <li><a href="chapter-12.html#s4">Named vs. Anonymous Schemas</a></li>
221
+
222
+ <li><a href="chapter-12.html#s5">Extending Schemas</a></li>
223
+
224
+ <li><a href="chapter-12.html#s6">Limitations</a></li>
225
+
226
+ </ol>
227
+ </li>
228
+
229
+ <li><strong>
230
+ <a href="chapter-13.html">
231
+ Listeners and Event Producers
232
+ </a>
233
+ </strong> <big>&larr;</big>
234
+ <ol type="1">
235
+
236
+ <li><a href="chapter-13.html#s1">Event Producers</a></li>
237
+
238
+ <li><a href="chapter-13.html#s2">Listeners</a></li>
239
+
240
+ <li><a href="chapter-13.html#s3">The Registry as an Event Producer</a></li>
241
+
242
+ </ol>
243
+ </li>
244
+
245
+ </ol>
246
+
247
+ <h2>API Reference</h2>
248
+
249
+ <ul>
250
+ <li><a href="http://copland.rubyforge.org/api/index.html">Copland API</a></li>
251
+ <li><a href="http://copland.rubyforge.org/packrat/index.html">Package Reference</a></li>
252
+ </ul>
253
+
254
+ <h2>Tutorials</h2>
255
+ <ol>
256
+
257
+ <li>
258
+ <a href="tutorial-1.html">
259
+ Creating Services
260
+ </a>
261
+ <br />
262
+ <p>The basics of creating new services in Copland.</p>
263
+ </li>
264
+
265
+ <li>
266
+ <a href="tutorial-2.html">
267
+ Service Factories
268
+ </a>
269
+ <br />
270
+ <p>Introduces the concept of a &#8220;service factory&#8221;, and shows how to use them to create complex services.</p>
271
+ </li>
272
+
273
+ <li>
274
+ <a href="tutorial-3.html">
275
+ Service Models
276
+ </a>
277
+ <br />
278
+ <p>Introduces the concept of the &#8220;service model&#8221;, and shows the difference between &#8220;singleton&#8221; and &#8220;prototype&#8221;.</p>
279
+ </li>
280
+
281
+ <li>
282
+ <a href="tutorial-4.html">
283
+ Logging Interceptor
284
+ </a>
285
+ <br />
286
+ <p>Shows how to use the logging interceptor to add logging for method invocations on any service.</p>
287
+ </li>
288
+
289
+ <li>
290
+ <a href="tutorial-5.html">
291
+ Configuration Points
292
+ </a>
293
+ <br />
294
+ <p>Demonstrates the use of configuration points for decentralizing service configuration.</p>
295
+ </li>
296
+
297
+ </ol>
298
+
299
+ <p align="center"><strong>More To Come...</strong></p>
300
+
301
+ <!--
302
+ <h2>Examples</h2>
303
+ <ol>
304
+
305
+ </ol>
306
+ -->
307
+
308
+ <div class="license">
309
+ <a href="http://creativecommons.org/licenses/by-sa/2.0/"><img alt="Creative Commons License" border="0" src="http://creativecommons.org/images/public/somerights" /></a><br />
310
+ This manual is licensed under a <a href="http://creativecommons.org/licenses/by-sa/2.0/">Creative Commons License</a>.
311
+ </div>
312
+ </div>
313
+
314
+ </td><td valign='top' width="100%">
315
+
316
+ <div id="content">
317
+
318
+ <h1>13. Listeners and Event Producers</h1>
319
+
320
+
321
+
322
+ <div class="section">
323
+ <p>Sometimes, you may have a service that produces events. In terms of a <span class="caps">GUI</span>, you might have a button that emits events liked &#8220;clicked&#8221;, &#8220;mouse over&#8221;, &#8220;mouse out&#8221;, &#8220;mouse down&#8221;, and so forth. Copland provides a framework for indicating that instances of a particular service point should listen for events from instances of another service point.<br />
324
+ </p>
325
+ </div>
326
+
327
+
328
+
329
+ <h2>
330
+ <a name="s1"></a>
331
+ 13.1. Event Producers
332
+ </h2>
333
+
334
+
335
+
336
+ <div class="section">
337
+ <p>At one end of this functionality is the <em>event producer</em>. Using the above example, this would be the button. It is the service that generates and emits the events.</p>
338
+
339
+ <p>Any service can be an event producer&#8212;all it requires is that the service implement an <code>#add_listener</code> method by which other services may be added as interested parties. Also, although there is nothing that prevents you from using non-singleton services as event producers, it really only works correctly with services using the <code>singleton</code> and <code>singleton-deferred</code> model.</p>
340
+
341
+ <p>When an event occurs, the producer should notify those registered listeners by invoking a method on them. The method should be named &#8220;on_#{event}&#8221; (where event is the name of the event), and it should accept the producer as the first argument, followed by any number of other arguments (as needed for the given event). The listener method should only be invoked if the listener responds to that method; otherwise, it should be silently skipped.</p>
342
+
343
+ <p>Optionally, if a listener does not respond to a specific event, the producer may look for a method called &#8220;on_any_event&#8221;; if the listener responds to that, that method may be invoked instead, with the producer as the first parameter and the event as the second, followed by any additional arguments.</p>
344
+
345
+ <p>To make it easier to create event producers, you can mixin the Copland::EventProducer module into your existing services. It provides several methods, including <code>#add_listener</code> and <code>#fire_event</code>.</p>
346
+
347
+ <pre>
348
+ require 'copland/event-producer'
349
+
350
+ class MyProducerService
351
+ include Copland::EventProducer
352
+
353
+ def click
354
+ do_something_about_it
355
+ fire_event :clicked
356
+ end
357
+
358
+ def mouse_over
359
+ do_something_else_about_it
360
+ fire_event :mouse_over
361
+ end
362
+ end
363
+ </pre>
364
+ </div>
365
+
366
+
367
+
368
+ <h2>
369
+ <a name="s2"></a>
370
+ 13.2. Listeners
371
+ </h2>
372
+
373
+
374
+
375
+ <div class="section">
376
+ <p>Listeners are at the other end of the producer/listener link. As with the event producer, any service can be a listener. It just needs to implement a method for each event that it is interested in, and then indicate (in its service point) that it wants to be registered as a listener of a particular service. Unlike event producers, the listeners can use any service model they like.</p>
377
+
378
+ <p>As described above, the listener methods are named &#8220;on_#{event}&#8221;, where &#8220;event&#8221; is the name of the event to listen to. Alternatively, a listener may declare a method called &#8220;on_any_event&#8221;, which will be called for any event that does not have an explicit listener method declared for.</p>
379
+
380
+ <pre>
381
+ class MyListenerService
382
+ def on_click( producer, *args )
383
+ puts "Argh! It was clicked!"
384
+ end
385
+
386
+ def on_any_event( producer, event, *args )
387
+ puts "Something happened: #{event}"
388
+ end
389
+ end
390
+ </pre>
391
+
392
+ <p>To register interest in the producer, use the <code>listen-to</code> element when defining the service point. This element expects an array of service point names. Every time the service point is instantiated, the list of <code>listen-to</code> elements will be processed and the new service will be added to each of those service points in turn, as a listener:</p>
393
+
394
+ <pre>
395
+ service-points:
396
+
397
+ Producer:
398
+ implementor: MyProducerService
399
+
400
+ Listener:
401
+ implementor: MyListenerService
402
+ listen-to:
403
+ - Producer
404
+ </pre>
405
+ </div>
406
+
407
+
408
+
409
+ <h2>
410
+ <a name="s3"></a>
411
+ 13.3. The Registry as an Event Producer
412
+ </h2>
413
+
414
+
415
+
416
+ <div class="section">
417
+ <p>Currently, Copland only comes with one event producer built in&#8212;the registry itself. Every time you instantiate a registry, it adds itself to itself as the &#8220;copland.Registry&#8221; service. When the registry is shutdown, it emits a <code>:registry_shutdown</code> event to all of its listeners.</p>
418
+
419
+ <p>Thus, if you have a service that you want to be able to do some cleanup when the registry is being shutdown, you can have that service listen to &#8220;copland.Registry&#8221;, and implement a listener method called <code>on_registry_shutdown</code> (or <code>on_any_event</code>).</p>
420
+ </div>
421
+
422
+
423
+
424
+
425
+ </div>
426
+
427
+ </td></tr>
428
+ </table>
429
+ </body>
430
+ </html>
@@ -14,8 +14,8 @@
14
14
  </div>
15
15
  </td><td valign='middle' align='right'>
16
16
  <div class="info">
17
- Copland Version: <strong>0.8.0</strong><br />
18
- Manual Last Updated: <strong>2004-09-27 03:37 GMT</strong>
17
+ Copland Version: <strong>1.0.0</strong><br />
18
+ Manual Last Updated: <strong>2004-10-12 02:22 GMT</strong>
19
19
  </div>
20
20
  </td></tr>
21
21
  </table>
@@ -39,13 +39,21 @@
39
39
 
40
40
  <li><a href="chapter-1.html#s1">What is Copland?</a></li>
41
41
 
42
- <li><a href="chapter-1.html#s2">Features</a></li>
42
+ <li><a href="chapter-1.html#s2">What Can Copland Do For Me?</a></li>
43
43
 
44
- <li><a href="chapter-1.html#s3">Getting Copland</a></li>
44
+ <li><a href="chapter-1.html#s3">Copland <em>sans</em> Buzzwords</a></li>
45
45
 
46
- <li><a href="chapter-1.html#s4">License Information</a></li>
46
+ <li><a href="chapter-1.html#s4">Copland <em>avec</em> Buzzwords</a></li>
47
47
 
48
- <li><a href="chapter-1.html#s5">Support</a></li>
48
+ <li><a href="chapter-1.html#s5">The Buzzwords Themselves</a></li>
49
+
50
+ <li><a href="chapter-1.html#s6">Features</a></li>
51
+
52
+ <li><a href="chapter-1.html#s7">Getting Copland</a></li>
53
+
54
+ <li><a href="chapter-1.html#s8">License Information</a></li>
55
+
56
+ <li><a href="chapter-1.html#s9">Support</a></li>
49
57
 
50
58
  </ol>
51
59
  </li>
@@ -149,7 +157,9 @@
149
157
 
150
158
  <li><a href="chapter-8.html#s1">Descriptor Syntax</a></li>
151
159
 
152
- <li><a href="chapter-8.html#s2">DefaultSymbolSource</a></li>
160
+ <li><a href="chapter-8.html#s2">FactoryDefaults</a></li>
161
+
162
+ <li><a href="chapter-8.html#s3">ApplicationDefaults</a></li>
153
163
 
154
164
  </ol>
155
165
  </li>
@@ -166,54 +176,68 @@
166
176
 
167
177
  <li>
168
178
  <a href="chapter-10.html">
179
+ Logging
180
+ </a>
181
+
182
+ <ol type="1">
183
+
184
+ <li><a href="chapter-10.html#s1">Log Factory</a></li>
185
+
186
+ <li><a href="chapter-10.html#s2">Configuration</a></li>
187
+
188
+ </ol>
189
+ </li>
190
+
191
+ <li>
192
+ <a href="chapter-11.html">
169
193
  Service Factories
170
194
  </a>
171
195
 
172
196
  <ol type="1">
173
197
 
174
- <li><a href="chapter-10.html#s1">Schemas</a></li>
198
+ <li><a href="chapter-11.html#s1">Schemas</a></li>
175
199
 
176
- <li><a href="chapter-10.html#s2">How do they work?</a></li>
200
+ <li><a href="chapter-11.html#s2">How do they work?</a></li>
177
201
 
178
- <li><a href="chapter-10.html#s3">BuilderFactory</a></li>
202
+ <li><a href="chapter-11.html#s3">BuilderFactory</a></li>
179
203
 
180
204
  </ol>
181
205
  </li>
182
206
 
183
207
  <li>
184
- <a href="chapter-11.html">
208
+ <a href="chapter-12.html">
185
209
  Schemas
186
210
  </a>
187
211
 
188
212
  <ol type="1">
189
213
 
190
- <li><a href="chapter-11.html#s1">Basic Format</a></li>
214
+ <li><a href="chapter-12.html#s1">Basic Format</a></li>
191
215
 
192
- <li><a href="chapter-11.html#s2">Subschemas</a></li>
216
+ <li><a href="chapter-12.html#s2">Subschemas</a></li>
193
217
 
194
- <li><a href="chapter-11.html#s3">Arrays</a></li>
218
+ <li><a href="chapter-12.html#s3">Arrays</a></li>
195
219
 
196
- <li><a href="chapter-11.html#s4">Named vs. Anonymous Schemas</a></li>
220
+ <li><a href="chapter-12.html#s4">Named vs. Anonymous Schemas</a></li>
197
221
 
198
- <li><a href="chapter-11.html#s5">Extending Schemas</a></li>
222
+ <li><a href="chapter-12.html#s5">Extending Schemas</a></li>
199
223
 
200
- <li><a href="chapter-11.html#s6">Limitations</a></li>
224
+ <li><a href="chapter-12.html#s6">Limitations</a></li>
201
225
 
202
226
  </ol>
203
227
  </li>
204
228
 
205
229
  <li>
206
- <a href="chapter-12.html">
230
+ <a href="chapter-13.html">
207
231
  Listeners and Event Producers
208
232
  </a>
209
233
 
210
234
  <ol type="1">
211
235
 
212
- <li><a href="chapter-12.html#s1">Event Producers</a></li>
236
+ <li><a href="chapter-13.html#s1">Event Producers</a></li>
213
237
 
214
- <li><a href="chapter-12.html#s2">Listeners</a></li>
238
+ <li><a href="chapter-13.html#s2">Listeners</a></li>
215
239
 
216
- <li><a href="chapter-12.html#s3">The Registry as an Event Producer</a></li>
240
+ <li><a href="chapter-13.html#s3">The Registry as an Event Producer</a></li>
217
241
 
218
242
  </ol>
219
243
  </li>