copland 0.8.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (184) hide show
  1. data/doc/README +88 -0
  2. data/doc/manual-html/chapter-1.html +454 -0
  3. data/doc/manual-html/chapter-10.html +399 -0
  4. data/doc/manual-html/chapter-11.html +600 -0
  5. data/doc/manual-html/chapter-12.html +406 -0
  6. data/doc/manual-html/chapter-2.html +382 -0
  7. data/doc/manual-html/chapter-3.html +424 -0
  8. data/doc/manual-html/chapter-4.html +432 -0
  9. data/doc/manual-html/chapter-5.html +381 -0
  10. data/doc/manual-html/chapter-6.html +364 -0
  11. data/doc/manual-html/chapter-7.html +434 -0
  12. data/doc/manual-html/chapter-8.html +373 -0
  13. data/doc/manual-html/chapter-9.html +324 -0
  14. data/doc/manual-html/copland.png +0 -0
  15. data/doc/manual-html/index.html +331 -0
  16. data/doc/manual-html/manual.css +179 -0
  17. data/doc/manual-html/tutorial-1.html +407 -0
  18. data/doc/manual-html/tutorial-2.html +451 -0
  19. data/doc/manual-html/tutorial-3.html +484 -0
  20. data/doc/manual-html/tutorial-4.html +446 -0
  21. data/doc/manual-html/tutorial-5.html +520 -0
  22. data/doc/manual/chapter.erb +18 -0
  23. data/doc/manual/example.erb +18 -0
  24. data/doc/manual/img/copland.png +0 -0
  25. data/doc/manual/index.erb +30 -0
  26. data/doc/manual/manual.css +179 -0
  27. data/doc/manual/manual.rb +239 -0
  28. data/doc/manual/manual.yml +2643 -0
  29. data/doc/manual/page.erb +102 -0
  30. data/doc/manual/tutorial.erb +30 -0
  31. data/doc/packages/copland.html +764 -0
  32. data/doc/packages/copland.lib.html +439 -0
  33. data/doc/packages/copland.remote.html +2096 -0
  34. data/doc/packages/copland.webrick.html +925 -0
  35. data/doc/packages/index.html +49 -0
  36. data/doc/packages/packrat.css +125 -0
  37. data/examples/calc/calc.rb +47 -0
  38. data/examples/calc/package.yml +35 -0
  39. data/examples/calc/services.rb +74 -0
  40. data/examples/solitaire-cipher/README +11 -0
  41. data/examples/solitaire-cipher/Rakefile +57 -0
  42. data/examples/solitaire-cipher/bin/main.rb +14 -0
  43. data/examples/solitaire-cipher/lib/cipher.rb +230 -0
  44. data/examples/solitaire-cipher/lib/cli.rb +24 -0
  45. data/examples/solitaire-cipher/lib/package.yml +106 -0
  46. data/examples/solitaire-cipher/test/tc_deck.rb +30 -0
  47. data/examples/solitaire-cipher/test/tc_key-stream.rb +19 -0
  48. data/examples/solitaire-cipher/test/tc_keying-algorithms.rb +31 -0
  49. data/examples/solitaire-cipher/test/tc_solitaire-cipher.rb +66 -0
  50. data/examples/solitaire-cipher/test/tc_unkeyed-algorithm.rb +17 -0
  51. data/examples/solitaire-cipher/test/tests.rb +2 -0
  52. data/lib/copland.rb +56 -0
  53. data/lib/copland/class-factory.rb +95 -0
  54. data/lib/copland/configuration-point.rb +38 -0
  55. data/lib/copland/configuration-point/common.rb +203 -0
  56. data/lib/copland/configuration-point/errors.rb +44 -0
  57. data/lib/copland/configuration-point/list.rb +59 -0
  58. data/lib/copland/configuration-point/map.rb +59 -0
  59. data/lib/copland/configuration/errors.rb +43 -0
  60. data/lib/copland/configuration/loader.rb +113 -0
  61. data/lib/copland/configuration/yaml/configuration-point.rb +87 -0
  62. data/lib/copland/configuration/yaml/implementor.rb +134 -0
  63. data/lib/copland/configuration/yaml/interceptor.rb +63 -0
  64. data/lib/copland/configuration/yaml/listener.rb +56 -0
  65. data/lib/copland/configuration/yaml/loader.rb +122 -0
  66. data/lib/copland/configuration/yaml/package.rb +125 -0
  67. data/lib/copland/configuration/yaml/parser.rb +71 -0
  68. data/lib/copland/configuration/yaml/schema.rb +165 -0
  69. data/lib/copland/configuration/yaml/service-point.rb +116 -0
  70. data/lib/copland/configuration/yaml/utils.rb +82 -0
  71. data/lib/copland/default-schema-processor.rb +144 -0
  72. data/lib/copland/errors.rb +82 -0
  73. data/lib/copland/event-producer.rb +95 -0
  74. data/lib/copland/impl/builder-factory.rb +112 -0
  75. data/lib/copland/impl/copland-config.yml +1 -0
  76. data/lib/copland/impl/include-exclude.rb +140 -0
  77. data/lib/copland/impl/logging-interceptor.rb +106 -0
  78. data/lib/copland/impl/package.yml +217 -0
  79. data/lib/copland/impl/startup.rb +116 -0
  80. data/lib/copland/impl/symbol-source-manager.rb +131 -0
  81. data/lib/copland/impl/symbol-source.rb +63 -0
  82. data/lib/copland/instantiator.rb +38 -0
  83. data/lib/copland/instantiator/abstract.rb +91 -0
  84. data/lib/copland/instantiator/complex.rb +96 -0
  85. data/lib/copland/instantiator/identity.rb +58 -0
  86. data/lib/copland/instantiator/simple.rb +68 -0
  87. data/lib/copland/interceptor-chain.rb +166 -0
  88. data/lib/copland/interceptor.rb +139 -0
  89. data/lib/copland/log-factory.rb +206 -0
  90. data/lib/copland/models.rb +39 -0
  91. data/lib/copland/models/abstract.rb +78 -0
  92. data/lib/copland/models/prototype-deferred.rb +58 -0
  93. data/lib/copland/models/prototype.rb +58 -0
  94. data/lib/copland/models/proxy.rb +100 -0
  95. data/lib/copland/models/singleton-deferred.rb +59 -0
  96. data/lib/copland/models/singleton.rb +77 -0
  97. data/lib/copland/models/threaded.rb +65 -0
  98. data/lib/copland/ordering.rb +123 -0
  99. data/lib/copland/package.rb +246 -0
  100. data/lib/copland/registry.rb +368 -0
  101. data/lib/copland/schema.rb +206 -0
  102. data/lib/copland/service-point.rb +282 -0
  103. data/lib/copland/utils.rb +221 -0
  104. data/lib/copland/version.rb +47 -0
  105. data/test/conf-test/list-bad-key.yml +30 -0
  106. data/test/conf-test/list-bad-missing.yml +28 -0
  107. data/test/conf-test/list-bad-type.yml +28 -0
  108. data/test/conf-test/list-good.yml +29 -0
  109. data/test/conf-test/map-bad-key.yml +25 -0
  110. data/test/conf-test/map-bad-missing.yml +24 -0
  111. data/test/conf-test/map-bad-type.yml +23 -0
  112. data/test/conf-test/map-good.yml +25 -0
  113. data/test/configuration-point/package.yml +52 -0
  114. data/test/configuration/yaml/config/copland-config.yml +2 -0
  115. data/test/configuration/yaml/config/module.yml +2 -0
  116. data/test/configuration/yaml/config/subdir/copland-config.yml +2 -0
  117. data/test/configuration/yaml/config/subdir/package.yml +4 -0
  118. data/test/configuration/yaml/defaults/package.yml +5 -0
  119. data/test/configuration/yaml/defaults/subdir/package.yml +4 -0
  120. data/test/configuration/yaml/tc_config-loader.rb +86 -0
  121. data/test/configuration/yaml/tc_configuration-point-processor.rb +134 -0
  122. data/test/configuration/yaml/tc_implementor-processor.rb +104 -0
  123. data/test/configuration/yaml/tc_interceptor-processor.rb +85 -0
  124. data/test/configuration/yaml/tc_listener-processor.rb +69 -0
  125. data/test/configuration/yaml/tc_loader.rb +74 -0
  126. data/test/configuration/yaml/tc_package-processor.rb +120 -0
  127. data/test/configuration/yaml/tc_parser.rb +94 -0
  128. data/test/configuration/yaml/tc_schema-parser.rb +160 -0
  129. data/test/configuration/yaml/tc_service-point-processor.rb +104 -0
  130. data/test/configuration/yaml/tc_type-validator.rb +90 -0
  131. data/test/custom-logger.yml +3 -0
  132. data/test/impl/logging/package.yml +44 -0
  133. data/test/impl/logging/services.rb +84 -0
  134. data/test/impl/startup/package.yml +46 -0
  135. data/test/impl/startup/services.rb +47 -0
  136. data/test/impl/symbols/package.yml +24 -0
  137. data/test/impl/symbols/services.rb +38 -0
  138. data/test/impl/tc_builder-factory.rb +173 -0
  139. data/test/impl/tc_logging-interceptor.rb +148 -0
  140. data/test/impl/tc_startup.rb +59 -0
  141. data/test/impl/tc_symbol-sources.rb +61 -0
  142. data/test/logger.yml +6 -0
  143. data/test/mock.rb +201 -0
  144. data/test/schema/bad-package.yml +65 -0
  145. data/test/schema/package.yml +102 -0
  146. data/test/schema/services.rb +5 -0
  147. data/test/services/package.yml +79 -0
  148. data/test/services/simple.rb +87 -0
  149. data/test/tc_class-factory.rb +93 -0
  150. data/test/tc_complex-instantiator.rb +107 -0
  151. data/test/tc_configuration-point-contrib.rb +74 -0
  152. data/test/tc_configuration-point-schema.rb +122 -0
  153. data/test/tc_configuration-point.rb +91 -0
  154. data/test/tc_default-schema-processor.rb +297 -0
  155. data/test/tc_identity-instantiator.rb +61 -0
  156. data/test/tc_interceptors.rb +84 -0
  157. data/test/tc_logger.rb +131 -0
  158. data/test/tc_models.rb +176 -0
  159. data/test/tc_package.rb +165 -0
  160. data/test/tc_proxy.rb +65 -0
  161. data/test/tc_registry.rb +141 -0
  162. data/test/tc_schema.rb +78 -0
  163. data/test/tc_service-point.rb +178 -0
  164. data/test/tc_service.rb +70 -0
  165. data/test/tc_simple-instantiator.rb +61 -0
  166. data/test/tests.rb +93 -0
  167. data/tutorial/01/main.rb +7 -0
  168. data/tutorial/01/package.yml +8 -0
  169. data/tutorial/01/tutorial.rb +7 -0
  170. data/tutorial/02/main.rb +10 -0
  171. data/tutorial/02/package.yml +27 -0
  172. data/tutorial/02/tutorial.rb +46 -0
  173. data/tutorial/03/main.rb +24 -0
  174. data/tutorial/03/package.yml +29 -0
  175. data/tutorial/03/tutorial.rb +48 -0
  176. data/tutorial/04/main.rb +24 -0
  177. data/tutorial/04/package.yml +35 -0
  178. data/tutorial/04/tutorial.rb +48 -0
  179. data/tutorial/05/functions/package.yml +16 -0
  180. data/tutorial/05/functions/services.rb +15 -0
  181. data/tutorial/05/main.rb +10 -0
  182. data/tutorial/05/package.yml +35 -0
  183. data/tutorial/05/tutorial.rb +53 -0
  184. metadata +260 -0
data/doc/manual-html/chapter-5.html ADDED
@@ -0,0 +1,381 @@
1
+ <html>
2
+ <head>
3
+ <title>Copland Manual :: Chapter 5: Packages</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>0.8.0</strong><br />
18
+ Manual Last Updated: <strong>2004-09-27 03:37 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">Features</a></li>
43
+
44
+ <li><a href="chapter-1.html#s3">Getting Copland</a></li>
45
+
46
+ <li><a href="chapter-1.html#s4">License Information</a></li>
47
+
48
+ <li><a href="chapter-1.html#s5">Support</a></li>
49
+
50
+ </ol>
51
+ </li>
52
+
53
+ <li>
54
+ <a href="chapter-2.html">
55
+ Justification
56
+ </a>
57
+
58
+ <ol type="1">
59
+
60
+ <li><a href="chapter-2.html#s1">IoC in One Paragraph</a></li>
61
+
62
+ <li><a href="chapter-2.html#s2">Why IoC?</a></li>
63
+
64
+ <li><a href="chapter-2.html#s3">A Case Study</a></li>
65
+
66
+ </ol>
67
+ </li>
68
+
69
+ <li>
70
+ <a href="chapter-3.html">
71
+ Getting Started
72
+ </a>
73
+
74
+ <ol type="1">
75
+
76
+ <li><a href="chapter-3.html#s1">Terminology</a></li>
77
+
78
+ <li><a href="chapter-3.html#s2">Quickstart</a></li>
79
+
80
+ </ol>
81
+ </li>
82
+
83
+ <li>
84
+ <a href="chapter-4.html">
85
+ Copland's Design
86
+ </a>
87
+
88
+ <ol type="1">
89
+
90
+ <li><a href="chapter-4.html#s1">HiveMind</a></li>
91
+
92
+ <li><a href="chapter-4.html#s2">Registry Initialization</a></li>
93
+
94
+ <li><a href="chapter-4.html#s3">Service Instantiation</a></li>
95
+
96
+ <li><a href="chapter-4.html#s4">Interceptor Chains</a></li>
97
+
98
+ </ol>
99
+ </li>
100
+
101
+ <li><strong>
102
+ <a href="chapter-5.html">
103
+ Packages
104
+ </a>
105
+ </strong> <big>&larr;</big>
106
+ <ol type="1">
107
+
108
+ <li><a href="chapter-5.html#s1">Descriptor Syntax</a></li>
109
+
110
+ <li><a href="chapter-5.html#s2">Tips</a></li>
111
+
112
+ </ol>
113
+ </li>
114
+
115
+ <li>
116
+ <a href="chapter-6.html">
117
+ Service Points
118
+ </a>
119
+
120
+ <ol type="1">
121
+
122
+ <li><a href="chapter-6.html#s1">Descriptor Syntax</a></li>
123
+
124
+ </ol>
125
+ </li>
126
+
127
+ <li>
128
+ <a href="chapter-7.html">
129
+ Service Models
130
+ </a>
131
+
132
+ <ol type="1">
133
+
134
+ <li><a href="chapter-7.html#s1">Standard Models</a></li>
135
+
136
+ <li><a href="chapter-7.html#s2">Deferred Instantiation</a></li>
137
+
138
+ <li><a href="chapter-7.html#s3">Custom Service Models</a></li>
139
+
140
+ </ol>
141
+ </li>
142
+
143
+ <li>
144
+ <a href="chapter-8.html">
145
+ Configuration Points
146
+ </a>
147
+
148
+ <ol type="1">
149
+
150
+ <li><a href="chapter-8.html#s1">Descriptor Syntax</a></li>
151
+
152
+ <li><a href="chapter-8.html#s2">DefaultSymbolSource</a></li>
153
+
154
+ </ol>
155
+ </li>
156
+
157
+ <li>
158
+ <a href="chapter-9.html">
159
+ Contributions
160
+ </a>
161
+
162
+ <ol type="1">
163
+
164
+ </ol>
165
+ </li>
166
+
167
+ <li>
168
+ <a href="chapter-10.html">
169
+ Service Factories
170
+ </a>
171
+
172
+ <ol type="1">
173
+
174
+ <li><a href="chapter-10.html#s1">Schemas</a></li>
175
+
176
+ <li><a href="chapter-10.html#s2">How do they work?</a></li>
177
+
178
+ <li><a href="chapter-10.html#s3">BuilderFactory</a></li>
179
+
180
+ </ol>
181
+ </li>
182
+
183
+ <li>
184
+ <a href="chapter-11.html">
185
+ Schemas
186
+ </a>
187
+
188
+ <ol type="1">
189
+
190
+ <li><a href="chapter-11.html#s1">Basic Format</a></li>
191
+
192
+ <li><a href="chapter-11.html#s2">Subschemas</a></li>
193
+
194
+ <li><a href="chapter-11.html#s3">Arrays</a></li>
195
+
196
+ <li><a href="chapter-11.html#s4">Named vs. Anonymous Schemas</a></li>
197
+
198
+ <li><a href="chapter-11.html#s5">Extending Schemas</a></li>
199
+
200
+ <li><a href="chapter-11.html#s6">Limitations</a></li>
201
+
202
+ </ol>
203
+ </li>
204
+
205
+ <li>
206
+ <a href="chapter-12.html">
207
+ Listeners and Event Producers
208
+ </a>
209
+
210
+ <ol type="1">
211
+
212
+ <li><a href="chapter-12.html#s1">Event Producers</a></li>
213
+
214
+ <li><a href="chapter-12.html#s2">Listeners</a></li>
215
+
216
+ <li><a href="chapter-12.html#s3">The Registry as an Event Producer</a></li>
217
+
218
+ </ol>
219
+ </li>
220
+
221
+ </ol>
222
+
223
+ <h2>API Reference</h2>
224
+
225
+ <ul>
226
+ <li><a href="http://copland.rubyforge.org/api/index.html">Copland API</a></li>
227
+ <li><a href="http://copland.rubyforge.org/packrat/index.html">Package Reference</a></li>
228
+ </ul>
229
+
230
+ <h2>Tutorials</h2>
231
+ <ol>
232
+
233
+ <li>
234
+ <a href="tutorial-1.html">
235
+ Creating Services
236
+ </a>
237
+ <br />
238
+ <p>The basics of creating new services in Copland.</p>
239
+ </li>
240
+
241
+ <li>
242
+ <a href="tutorial-2.html">
243
+ Service Factories
244
+ </a>
245
+ <br />
246
+ <p>Introduces the concept of a &#8220;service factory&#8221;, and shows how to use them to create complex services.</p>
247
+ </li>
248
+
249
+ <li>
250
+ <a href="tutorial-3.html">
251
+ Service Models
252
+ </a>
253
+ <br />
254
+ <p>Introduces the concept of the &#8220;service model&#8221;, and shows the difference between &#8220;singleton&#8221; and &#8220;prototype&#8221;.</p>
255
+ </li>
256
+
257
+ <li>
258
+ <a href="tutorial-4.html">
259
+ Logging Interceptor
260
+ </a>
261
+ <br />
262
+ <p>Shows how to use the logging interceptor to add logging for method invocations on any service.</p>
263
+ </li>
264
+
265
+ <li>
266
+ <a href="tutorial-5.html">
267
+ Configuration Points
268
+ </a>
269
+ <br />
270
+ <p>Demonstrates the use of configuration points for decentralizing service configuration.</p>
271
+ </li>
272
+
273
+ </ol>
274
+
275
+ <p align="center"><strong>More To Come...</strong></p>
276
+
277
+ <!--
278
+ <h2>Examples</h2>
279
+ <ol>
280
+
281
+ </ol>
282
+ -->
283
+
284
+ <div class="license">
285
+ <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 />
286
+ This manual is licensed under a <a href="http://creativecommons.org/licenses/by-sa/2.0/">Creative Commons License</a>.
287
+ </div>
288
+ </div>
289
+
290
+ </td><td valign='top' width="100%">
291
+
292
+ <div id="content">
293
+
294
+ <h1>5. Packages</h1>
295
+
296
+
297
+
298
+ <div class="section">
299
+ <p>Packages are the unit of organization in Copland. All service and configuration points are grouped in packages.<br />
300
+ </p>
301
+ </div>
302
+
303
+
304
+
305
+ <h2>
306
+ <a name="s1"></a>
307
+ 5.1. Descriptor Syntax
308
+ </h2>
309
+
310
+
311
+
312
+ <div class="section">
313
+ <p>Each package is described in a single file, named &#8220;package.yml&#8221;. (You can actually change what the descriptor file name ought to be&#8212;the default, though, is &#8220;package.yml&#8221;). It will typically contain all of the services defined in the same directory. In keeping with standard <span class="caps">YAML</span> syntax, this file should begin with a single line consisting solely of three dashes: <code>---</code>.</p>
314
+
315
+ <p>The file may contain the following attributes:</p>
316
+
317
+ <table class="list">
318
+ <tr>
319
+ <td style="vertical-align:top;"><code>id</code></td>
320
+ <td>This is the name of the package. It must be a string, and it must be unique. If the registry encounters a package named identically to some other package it has already parsed, it will raise an exception.</td>
321
+ </tr>
322
+ <tr>
323
+ <td style="vertical-align:top;"><code>require</code></td>
324
+ <td>This is a list of other (non-core) packages that this package depends on. For example, to take advantage of any of the services in the &#8220;copland.lib&#8221; namespace, you would need to add &#8220;copland/lib&#8221; to the require list for the package that needs those services.</td>
325
+ </tr>
326
+ <tr>
327
+ <td style="vertical-align:top;"><code>description</code></td>
328
+ <td>This is an (optional) description of the current package. It is useful for documentation purposes, but is not used at all by Copland itself.</td>
329
+ </tr>
330
+ <tr>
331
+ <td style="vertical-align:top;"><code>configuration-points</code></td>
332
+ <td>This must contain a hash of values, each key of which names and references the definition of a <em>configuration point</em> (q.v.).</td>
333
+ </tr>
334
+ <tr>
335
+ <td style="vertical-align:top;"><code>contributions</code></td>
336
+ <td>This must contain a hash of values, each key of names a contribution to some configuration point. (See the chapter on contributions for more information.)</td>
337
+ </tr>
338
+ <tr>
339
+ <td style="vertical-align:top;"><code>service-points</code></td>
340
+ <td>This must contain a hash of values, each key of which names and references the definition of a <em>service point</em> (q.v.).</td>
341
+ </tr>
342
+ </table>
343
+
344
+ <p>Of the attributes descibed above, only the <code>id</code> attribute is required, though it makes little sense to define a package that does not include at least one configuration point, contribution, or service point.</p>
345
+
346
+ <p>Also, if your package references any non-core packages (like &#8220;copland.lib&#8221; or &#8220;copland.remote&#8221;), you will need to add the requisite libraries to your package&#8217;s <code>require</code> clause.<br />
347
+ </p>
348
+ </div>
349
+
350
+
351
+
352
+ <h2>
353
+ <a name="s2"></a>
354
+ 5.2. Tips
355
+ </h2>
356
+
357
+
358
+
359
+ <div class="section">
360
+ <p>Name your packages consistently. Here is a recommended naming convention:</p>
361
+
362
+ <ul>
363
+ <li>Use dashes instead of underscores in your package names.</li>
364
+ <li>Make package names all lowercase.</li>
365
+ <li>Name your primary package after your application.</li>
366
+ <li>If your application uses more than one package (and large applications very well may), prefix each package name with the name of your application, followed by a dot. In other words, if your application was named &#8220;Astroscopus&#8221;, and you had a subpackage named &#8220;notewise&#8221;, you would name your primary package &#8220;astroscopus&#8221;, and the subpackage &#8220;astroscopus.notewise&#8221;. This gives your packages a hierarchical feel, though there is nothing saying they need to be laid out in a hierarchical directory structure.</li>
367
+ <li>If you are distributing a package that you created for others to use, name the package with your name or company (or website) as the primary package name, and your library as the secondary name. For instance, if your company was &#8220;Interrelated Autorotation, Inc.&#8221;, and you created a library called &#8220;papillomatosis&#8221;, you might name your package &#8220;interrelated-autorotation.papillomatosis&#8221;.</li>
368
+ </ul>
369
+
370
+ <p>Try to group the service points and configuration points in your packages by common functionality. Don&#8217;t be afraid to create new packages where necessary to separate functional groups. Although having many packages may make your application&#8217;s start-up time a little slower (and it will only be a little), it is worth the benefits to maintainance it will add.</p>
371
+ </div>
372
+
373
+
374
+
375
+
376
+ </div>
377
+
378
+ </td></tr>
379
+ </table>
380
+ </body>
381
+ </html>
data/doc/manual-html/chapter-6.html ADDED
@@ -0,0 +1,364 @@
1
+ <html>
2
+ <head>
3
+ <title>Copland Manual :: Chapter 6: Service Points</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>0.8.0</strong><br />
18
+ Manual Last Updated: <strong>2004-09-27 03:37 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">Features</a></li>
43
+
44
+ <li><a href="chapter-1.html#s3">Getting Copland</a></li>
45
+
46
+ <li><a href="chapter-1.html#s4">License Information</a></li>
47
+
48
+ <li><a href="chapter-1.html#s5">Support</a></li>
49
+
50
+ </ol>
51
+ </li>
52
+
53
+ <li>
54
+ <a href="chapter-2.html">
55
+ Justification
56
+ </a>
57
+
58
+ <ol type="1">
59
+
60
+ <li><a href="chapter-2.html#s1">IoC in One Paragraph</a></li>
61
+
62
+ <li><a href="chapter-2.html#s2">Why IoC?</a></li>
63
+
64
+ <li><a href="chapter-2.html#s3">A Case Study</a></li>
65
+
66
+ </ol>
67
+ </li>
68
+
69
+ <li>
70
+ <a href="chapter-3.html">
71
+ Getting Started
72
+ </a>
73
+
74
+ <ol type="1">
75
+
76
+ <li><a href="chapter-3.html#s1">Terminology</a></li>
77
+
78
+ <li><a href="chapter-3.html#s2">Quickstart</a></li>
79
+
80
+ </ol>
81
+ </li>
82
+
83
+ <li>
84
+ <a href="chapter-4.html">
85
+ Copland's Design
86
+ </a>
87
+
88
+ <ol type="1">
89
+
90
+ <li><a href="chapter-4.html#s1">HiveMind</a></li>
91
+
92
+ <li><a href="chapter-4.html#s2">Registry Initialization</a></li>
93
+
94
+ <li><a href="chapter-4.html#s3">Service Instantiation</a></li>
95
+
96
+ <li><a href="chapter-4.html#s4">Interceptor Chains</a></li>
97
+
98
+ </ol>
99
+ </li>
100
+
101
+ <li>
102
+ <a href="chapter-5.html">
103
+ Packages
104
+ </a>
105
+
106
+ <ol type="1">
107
+
108
+ <li><a href="chapter-5.html#s1">Descriptor Syntax</a></li>
109
+
110
+ <li><a href="chapter-5.html#s2">Tips</a></li>
111
+
112
+ </ol>
113
+ </li>
114
+
115
+ <li><strong>
116
+ <a href="chapter-6.html">
117
+ Service Points
118
+ </a>
119
+ </strong> <big>&larr;</big>
120
+ <ol type="1">
121
+
122
+ <li><a href="chapter-6.html#s1">Descriptor Syntax</a></li>
123
+
124
+ </ol>
125
+ </li>
126
+
127
+ <li>
128
+ <a href="chapter-7.html">
129
+ Service Models
130
+ </a>
131
+
132
+ <ol type="1">
133
+
134
+ <li><a href="chapter-7.html#s1">Standard Models</a></li>
135
+
136
+ <li><a href="chapter-7.html#s2">Deferred Instantiation</a></li>
137
+
138
+ <li><a href="chapter-7.html#s3">Custom Service Models</a></li>
139
+
140
+ </ol>
141
+ </li>
142
+
143
+ <li>
144
+ <a href="chapter-8.html">
145
+ Configuration Points
146
+ </a>
147
+
148
+ <ol type="1">
149
+
150
+ <li><a href="chapter-8.html#s1">Descriptor Syntax</a></li>
151
+
152
+ <li><a href="chapter-8.html#s2">DefaultSymbolSource</a></li>
153
+
154
+ </ol>
155
+ </li>
156
+
157
+ <li>
158
+ <a href="chapter-9.html">
159
+ Contributions
160
+ </a>
161
+
162
+ <ol type="1">
163
+
164
+ </ol>
165
+ </li>
166
+
167
+ <li>
168
+ <a href="chapter-10.html">
169
+ Service Factories
170
+ </a>
171
+
172
+ <ol type="1">
173
+
174
+ <li><a href="chapter-10.html#s1">Schemas</a></li>
175
+
176
+ <li><a href="chapter-10.html#s2">How do they work?</a></li>
177
+
178
+ <li><a href="chapter-10.html#s3">BuilderFactory</a></li>
179
+
180
+ </ol>
181
+ </li>
182
+
183
+ <li>
184
+ <a href="chapter-11.html">
185
+ Schemas
186
+ </a>
187
+
188
+ <ol type="1">
189
+
190
+ <li><a href="chapter-11.html#s1">Basic Format</a></li>
191
+
192
+ <li><a href="chapter-11.html#s2">Subschemas</a></li>
193
+
194
+ <li><a href="chapter-11.html#s3">Arrays</a></li>
195
+
196
+ <li><a href="chapter-11.html#s4">Named vs. Anonymous Schemas</a></li>
197
+
198
+ <li><a href="chapter-11.html#s5">Extending Schemas</a></li>
199
+
200
+ <li><a href="chapter-11.html#s6">Limitations</a></li>
201
+
202
+ </ol>
203
+ </li>
204
+
205
+ <li>
206
+ <a href="chapter-12.html">
207
+ Listeners and Event Producers
208
+ </a>
209
+
210
+ <ol type="1">
211
+
212
+ <li><a href="chapter-12.html#s1">Event Producers</a></li>
213
+
214
+ <li><a href="chapter-12.html#s2">Listeners</a></li>
215
+
216
+ <li><a href="chapter-12.html#s3">The Registry as an Event Producer</a></li>
217
+
218
+ </ol>
219
+ </li>
220
+
221
+ </ol>
222
+
223
+ <h2>API Reference</h2>
224
+
225
+ <ul>
226
+ <li><a href="http://copland.rubyforge.org/api/index.html">Copland API</a></li>
227
+ <li><a href="http://copland.rubyforge.org/packrat/index.html">Package Reference</a></li>
228
+ </ul>
229
+
230
+ <h2>Tutorials</h2>
231
+ <ol>
232
+
233
+ <li>
234
+ <a href="tutorial-1.html">
235
+ Creating Services
236
+ </a>
237
+ <br />
238
+ <p>The basics of creating new services in Copland.</p>
239
+ </li>
240
+
241
+ <li>
242
+ <a href="tutorial-2.html">
243
+ Service Factories
244
+ </a>
245
+ <br />
246
+ <p>Introduces the concept of a &#8220;service factory&#8221;, and shows how to use them to create complex services.</p>
247
+ </li>
248
+
249
+ <li>
250
+ <a href="tutorial-3.html">
251
+ Service Models
252
+ </a>
253
+ <br />
254
+ <p>Introduces the concept of the &#8220;service model&#8221;, and shows the difference between &#8220;singleton&#8221; and &#8220;prototype&#8221;.</p>
255
+ </li>
256
+
257
+ <li>
258
+ <a href="tutorial-4.html">
259
+ Logging Interceptor
260
+ </a>
261
+ <br />
262
+ <p>Shows how to use the logging interceptor to add logging for method invocations on any service.</p>
263
+ </li>
264
+
265
+ <li>
266
+ <a href="tutorial-5.html">
267
+ Configuration Points
268
+ </a>
269
+ <br />
270
+ <p>Demonstrates the use of configuration points for decentralizing service configuration.</p>
271
+ </li>
272
+
273
+ </ol>
274
+
275
+ <p align="center"><strong>More To Come...</strong></p>
276
+
277
+ <!--
278
+ <h2>Examples</h2>
279
+ <ol>
280
+
281
+ </ol>
282
+ -->
283
+
284
+ <div class="license">
285
+ <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 />
286
+ This manual is licensed under a <a href="http://creativecommons.org/licenses/by-sa/2.0/">Creative Commons License</a>.
287
+ </div>
288
+ </div>
289
+
290
+ </td><td valign='top' width="100%">
291
+
292
+ <div id="content">
293
+
294
+ <h1>6. Service Points</h1>
295
+
296
+
297
+
298
+ <div class="section">
299
+ <p>A <em>service point</em> is a definition of a service. It describes how and when the service should be instantiated, what parameters should be passed to it when it is created and what properties assigned, what other services it should listen to, and so forth. You could say that a service point is to a service, as a class is to an object. That is to say, a service point is simply a template for how a service should be created.<br />
300
+ </p>
301
+ </div>
302
+
303
+
304
+
305
+ <h2>
306
+ <a name="s1"></a>
307
+ 6.1. Descriptor Syntax
308
+ </h2>
309
+
310
+
311
+
312
+ <div class="section">
313
+ <p>Every service point must be defined as part of the &#8220;service-points&#8221; section of a package descriptor. The id (or name) of the service point will be the key used in that section to reference it, and it may contain any character you wish except for a &#8221;.&#8221;. Also, if you use any character that <span class="caps">YAML</span> treats specially (like commas, or colons), you&#8217;ll need to put the service name in quotes.</p>
314
+
315
+ <p>Whenever the name of a class is required (for a service, for instance), it must be in a particular format. The name of the class must be prefixed with the path that must be required (ie, the file that contains the class), followed by a forward slash (&#8221;/&#8221;), followed by the complete name of the class (including any modules that it is defined inside of). For example:</p>
316
+
317
+ <pre>
318
+ some/special/service/MyServices::MyService
319
+ </pre>
320
+
321
+ <p>The above example indicates a class named <code>MyService</code>, defined inside of a module called <code>MyServices</code>, and which is contained in a file called <code>some/special/service.rb</code>.</p>
322
+
323
+ <p>The allowed attributes of a service point are:</p>
324
+
325
+ <table class="list">
326
+ <tr>
327
+ <td style="vertical-align:top;"><code>description</code></td>
328
+ <td>this (optional) attribute is useful for documentation purposes, but has no use at all inside Copland.</td>
329
+ </tr>
330
+ <tr>
331
+ <td style="vertical-align:top;"><code>model</code></td>
332
+ <td>This describes how (and when) the service will actually be instantiated. It must be either <code>simple</code>, <code>simple-deferred</code>, <code>singleton</code>, <code>singleton-deferred</code>, <code>threaded</code>, or <code>pooled</code> (or, if you&#8217;ve defined a custom service model, the name of that custom service model). If this attribute is not specified, it defaults to <code>singleton-deferred</code>. (See the chapter on &#8220;Service Models&#8221; for more information.)</td>
333
+ </tr>
334
+ <tr>
335
+ <td style="vertical-align:top;"><code>implementor</code></td>
336
+ <td> This describes how the service should be <em>implemented</em>. If the value of this attribute is a string, then it must be the name of the class to instantiate. (If the class includes the Singleton mixin, then the singleton instance will be returned; otherwise a new instance of the class will be created.) If this value is a map, then it may contain at the key <code>factory</code>. This must identify a <em>factory service</em> which will be used to create the new service. (If omitted, it defaults to <code>copland.BuilderFactory</code>.) In addition to the <code>factory</code> attribute, the hash should contain any other attributes required by the service factory that was specified. See the documentation for the corresponding service factory for a description of which attributes are available.</td>
337
+ </tr>
338
+ <tr>
339
+ <td style="vertical-align:top;"><code>interceptors</code></td>
340
+ <td>This must be an array of interceptor definitions, each of which is a hash. The only required key in each hash is <code>service</code>, which names the interceptor factory service to use when instantiating the corresponding interceptor. The other allowed attributes are <code>before</code> and <code>after</code>, which may be used to define the order in which the interceptors are applied. Besides those two attributes, some interceptors may allow additional attributes to be specified in order to configure them. See the documentation for those interceptors for more information.</td>
341
+ </tr>
342
+ <tr>
343
+ <td style="vertical-align:top;"><code>schema</code></td>
344
+ <td>This must be either a string or a hash. If it is a string, then it references another schema (either in this package or a different one). Otherwise, it&#8217;s format is described in more detail in the chapter &#8220;Schemas&#8221;. This is only needed by services that define service or interceptor factories.</td>
345
+ </tr>
346
+ <tr>
347
+ <td style="vertical-align:top;"><code>listen-to</code></td>
348
+ <td>This must be an array of service point names. If the referrenced service points are not defined in the same package as the current service point, their full names (including package) must be given, otherwise the package name may be omitted. Every time the current service point is instantiated, the new instance will be added as a listener to each of the service points listed here, to be notified when some service-specific event is triggered. See the chapter on &#8220;Listeners and Event Producers&#8221; for more information.</td>
349
+ </tr>
350
+ </table>
351
+
352
+ <p>Of these attributes, only <code>implementor</code> is required.<br />
353
+ </p>
354
+ </div>
355
+
356
+
357
+
358
+
359
+ </div>
360
+
361
+ </td></tr>
362
+ </table>
363
+ </body>
364
+ </html>