1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
|
<html>
<head>
<title>Needle Manual :: Chapter 2: Registry</title>
<link type="text/css" rel="stylesheet" href="manual.css" />
</head>
<body>
<div id="banner">
<table border='0' cellpadding='0' cellspacing='0' width='100%'>
<tr><td valign='top' align='left'>
<div class="title">
<span class="product">Needle—</span><br />
<span class="tagline">to the point --></span>
</div>
</td><td valign='middle' align='right'>
<div class="info">
Needle Version: <strong>1.2.0</strong><br />
Manual Last Updated: <strong>2004-11-18 15:36 GMT</strong>
</div>
</td></tr>
</table>
</div>
<table border='0' width='100%' cellpadding='0' cellspacing='0'>
<tr><td valign='top'>
<div id="navigation">
<h1>Needle Manual</h1>
<h2>Chapters</h2>
<ol type="I">
<li>
<a href="chapter-1.html">
Introduction
</a>
<ol type="1">
<li><a href="chapter-1.html#s1">What is Needle?</a></li>
<li><a href="chapter-1.html#s2">How Can It Help Me?</a></li>
<li><a href="chapter-1.html#s3">Alternatives</a></li>
<li><a href="chapter-1.html#s4">License Information</a></li>
<li><a href="chapter-1.html#s5">Support</a></li>
</ol>
</li>
<li><strong>
<a href="chapter-2.html">
Registry
</a>
</strong> <big>←</big>
<ol type="1">
<li><a href="chapter-2.html#s1">Overview</a></li>
<li><a href="chapter-2.html#s2">Creating</a></li>
<li><a href="chapter-2.html#s3">Services</a></li>
<li><a href="chapter-2.html#s4">Namespaces</a></li>
</ol>
</li>
<li>
<a href="chapter-3.html">
Service Locator
</a>
<ol type="1">
<li><a href="chapter-3.html#s1">Overview</a></li>
<li><a href="chapter-3.html#s2">Conventional Architecture</a></li>
<li><a href="chapter-3.html#s3">Locator Pattern</a></li>
</ol>
</li>
<li>
<a href="chapter-4.html">
Dependency Injection
</a>
<ol type="1">
<li><a href="chapter-4.html#s1">Overview</a></li>
<li><a href="chapter-4.html#s2">Setup</a></li>
</ol>
</li>
<li>
<a href="chapter-5.html">
Interceptors
</a>
<ol type="1">
<li><a href="chapter-5.html#s1">Overview</a></li>
<li><a href="chapter-5.html#s2">Architecture</a></li>
<li><a href="chapter-5.html#s3">Attaching</a></li>
<li><a href="chapter-5.html#s4">Ordering</a></li>
<li><a href="chapter-5.html#s5">Custom</a></li>
</ol>
</li>
<li>
<a href="chapter-6.html">
Service Models
</a>
<ol type="1">
<li><a href="chapter-6.html#s1">Overview</a></li>
<li><a href="chapter-6.html#s2">Pipelines</a></li>
<li><a href="chapter-6.html#s3">Models</a></li>
</ol>
</li>
<li>
<a href="chapter-7.html">
Logging
</a>
<ol type="1">
<li><a href="chapter-7.html#s1">Overview</a></li>
<li><a href="chapter-7.html#s2">LogFactory</a></li>
<li><a href="chapter-7.html#s3">Configuration</a></li>
</ol>
</li>
<li>
<a href="chapter-8.html">
Service Libraries
</a>
<ol type="1">
<li><a href="chapter-8.html#s1">Overview</a></li>
<li><a href="chapter-8.html#s2">Creating Libraries</a></li>
<li><a href="chapter-8.html#s3">Using Libraries</a></li>
</ol>
</li>
<li>
<a href="chapter-9.html">
Customizing Needle
</a>
<ol type="1">
<li><a href="chapter-9.html#s1">Namespaces</a></li>
<li><a href="chapter-9.html#s2">Interceptors</a></li>
<li><a href="chapter-9.html#s3">Contexts</a></li>
</ol>
</li>
</ol>
<h2>Other Documentation</h2>
<ul>
<li><a href="http://needle.rubyforge.org/api/index.html">Needle API</a></li>
<li><a href="http://needle.rubyforge.org/faq.html">Needle FAQ</a></li>
</ul>
<h2>Tutorials</h2>
<ol>
</ol>
<p align="center"><strong>More To Come...</strong></p>
<div class="license">
<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 />
This manual is licensed under a <a href="http://creativecommons.org/licenses/by-sa/2.0/">Creative Commons License</a>.
</div>
</div>
</td><td valign='top' width="100%">
<div id="content">
<h1>2. Registry</h1>
<h2>
<a name="s1"></a>
2.1. Overview
</h2>
<div class="section">
<p>The registry is at the heart of any dependency-injected application or library. All services are registered with the registry, so that when an application needs an instance of a particular service, it may obtain that service reference by querying the registry.</p>
<p>In order to use Needle, you only really <em>need</em> to understand how to create and manipulate registry objects.</p>
</div>
<h2>
<a name="s2"></a>
2.2. Creating
</h2>
<div class="section">
<p>Creating a registry is as simple as calling <code>Needle::Registry.new</code>. This will give you a new registry object, bootstrapped to contain a few general services.</p>
<pre>
require 'needle'
registry = Needle::Registry.new
</pre>
<p>Once you have the reference to the registry, you can register services with it, create new namespaces in it, and so forth.</p>
<p>Alternatively, you can pass a block to <code>#new</code>:</p>
<pre>
registry = Needle::Registry.new do |r|
...
end
</pre>
<p>The parameter to the block will be a reference to the registry. This allows you to register services with the registry as soon as it is created.</p>
<p>Another convenience method is <code>#define!</code>:</p>
<pre>
registry = Needle::Registry.define! do
...
end
</pre>
<p>This block accepts no parameters, and evaluates the block as if it were passed to <code>Registry#define!</code> (see below).</p>
<p>There can be problems with using <code>define!</code>, however, since it uses <code>instance_eval</code> to evaluate the block within the context of another object. If you find yourself running into scoping issues, you might want to consider using <code>#define</code>:</p>
<pre>
registry = Needle::Registry.define do |b|
...
end
</pre>
<p>This block accepts a single parameter—a “builder” object to aid in registering services—and evaluates the block as if it were passed to <code>Registry#define</code> (see below).</p>
</div>
<h2>
<a name="s3"></a>
2.3. Services
</h2>
<div class="section">
<p>Registering services with a Needle registry is very straightforward. The simplest way to do it is:</p>
<pre>
registry.register( :foo ) { Bar.new }
</pre>
<p>The above will register a new service with the registry, naming it <code>:foo</code>. When <code>:foo</code> is requested from the registry, a new instance of <code>Bar</code> will be instantiated and returned.</p>
<p>You get services from the registry in either of two ways:</p>
<pre>
# Treating the registry as a Hash
svc = registry[:foo]
# Treating the service as a property of the registry
svc = registry.foo
</pre>
<h3>Convenience Methods</h3>
<p>Because you will often need to register many services with a registry at once, two convenience methods have been provided to make this use case lean and mean.</p>
<p>The first is <code>define</code>. Just pass a block to define that accepts one parameter. This parameter will be a “builder” object that allows you to define services just by sending them as messages to the builder:</p>
<pre>
registry.define do |b|
b.foo { Bar.new }
b.bar { Foo.new }
...
end
</pre>
<p>Alternative, you can call <code>define!</code>, passing a block that accepts no parameters. This block will be evaluated in the “builder” object’s context, with any unrecognized method call being interpreted as a new service registration of that name:</p>
<pre>
registry.define! do
foo { Bar.new }
bar { Foo.new }
...
end
</pre>
<p>Both of the above will register two new services with the registry, <code>:foo</code> and <code>:bar</code>.</p>
<h3>Default Lifecycle</h3>
<p>By default, a service is only instantiated once per registry. This means that (using the above example) if the service <code>:foo</code> were queried twice, the registry would return the same object for both queries:</p>
<pre>
svc1 = registry.foo
svc2 = registry.foo
p svc1.object_id == svc2.object_id #=> true
</pre>
<p>You can change this behavior, with <em>service models</em>. See the chapter on Service Models for more information.</p>
<h3>Parameterized Services</h3>
<p>Needle also supports <em>parameterized services</em>. These are services that, when requested, require contextual information to be passed as a parameter so that the service can be correctly initialized.</p>
<p>Consider the following example, in which some hypothetical <code>Printer</code> class represents any of a number of printers, based on a parameter given to its constructor.</p>
<pre>
registry.register( :printer, :model => :multiton ) do |c,p,name|
Printer.new( c.log_for( p ), name )
end
mono = registry.printer( :monochrome )
color = registry.printer( :color )
</pre>
<p>There are a few things to note about the above example:</p>
<ol>
<li>The <code>:multiton</code> model is explicitly requested. This is necessary because the default service model (<code>:singleton</code>) does not allow parameterized services. Most of the time, you’ll use the multiton service model with parameterized services, but you don’t have to. You could also use any of the prototype models as well.
</li>
<li>The constructor block for the <code>:printer</code> service takes three parameters, <code>c</code>, <code>p</code>, and <code>name</code>. The first two parameters, <code>c</code> and <code>p</code>, represent the container and the service point, respectively. Any parameters after those two are the contextual parameters given when the service is requested. In this case, there is only one contextual parameter: the name of the printer.
</li>
<li>Notice the first parameter to the Printer constructor: <code>c.log_for(p)</code>. This is itself invoking a parameterized service, named <code>:log_for</code>, and passing <code>p</code> as the contextual information. This will return a new logger handle for the service point <code>p</code> (i.e., the current service point).
</li>
<li>See how the printer service is requested on the last two lines. In this case, the <code>#printer</code> message is sent to the registry with a single parameter. You can also request the service in two other ways:</li>
</ol>
<pre>
dot_matrix = registry[ :printer, :dot_matrix ]
ink_jet = registry.get( :printer, :ink_jet )
</pre>
<p>Choose the style that works best for you.</p>
</div>
<h2>
<a name="s4"></a>
2.4. Namespaces
</h2>
<div class="section">
<p>Namespaces allow you to organize your services. The feature has many different applications, including:</p>
<ol>
<li>Third-parties may distribute Needle-enabled libraries without worrying about their choice of service names conflicting with the service names of their clients.</li>
<li>Developers may organize complex applications into modules, and the service definitions may be stored in the registry to reflect that organization.</li>
<li>Services deeper in the hierarchy may override services higher up.</li>
</ol>
<p>Creating a namespace is as easy as invoking the <code>#namespace</code> method of the registry (or of another namespace):</p>
<pre>
registry.namespace :stuff
</pre>
<p>This would create a new namespace in the registry called <code>:stuff</code>. The application may then proceed to register services inside that namespace:</p>
<pre>
registry.stuff.register( :foo ) { Bar.new }
...
svc = registry.stuff.foo
</pre>
<p>Here’s a tip: <em>namespaces are just a special kind of service.</em> This means that you can access namespaces in the same ways that you can access services:</p>
<pre>
svc = registry[:stuff][:foo]
</pre>
<h3>Convenience Methods</h3>
<p>Because it is often the case that you will be creating a namespace and then immediately registering services on it, you can pass a block to <code>namespace</code>. The block will receive a reference to the new namespace:</p>
<pre>
registry.namespace :stuff do |spc|
spc.register( :foo ) { Bar.new }
...
end
</pre>
<p>If you prefer the <code>define</code> approach to registering services, you may like <code>namespace_define</code>, which creates the new namespace and immediately calls <code>define</code> on it:</p>
<pre>
registry.namespace_define :stuff do |b|
b.foo { Bar.new }
...
end
</pre>
<p>And, to mirror the <code>namespace_define</code> method, there is also a <code>namespace_define!</code> method. This method creates a new namespace and then does a <code>define!</code> call on that namespace.</p>
<pre>
registry.namespace_define! :stuff do
foo { Bar.new }
...
end
</pre>
<p>The above code would create a new namespace called <code>:stuff</code> in the registry, and would then proceed to register a service called <code>:foo</code> in the new namespace.</p>
</div>
</div>
</td></tr>
</table>
</body>
</html>
|
