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/README ADDED
@@ -0,0 +1,88 @@
1
+ = Copland IoC Container
2
+
3
+ Copland is an Inversion of Control (IoC) container, in the same vein as
4
+ HiveMind[http://jakarta.apache.org/hivemind],
5
+ Spring[http://www.springframework.org], and
6
+ PicoContainer[http://www.picocontainer.org] (in the Java universe). It borrows
7
+ concepts, terminology, and even some architecture from HiveMind, with the exception
8
+ that it uses YAML[http://www.yaml.org] for the package descriptors instead of XML.
9
+
10
+ == Downloading
11
+
12
+ You may download Copland from Copland's RubyForge project, at http://rubyforge.org/projects/copland.
13
+ Copland is distributed both as a RubyGem, and as a Ruby library.
14
+
15
+ == Installation
16
+
17
+ Copland is distributed as a gem, which makes it extremely easy to download, install, and
18
+ use. However, it requires that you have RubyGems[http://rubygems.rubyforge.org] installed,
19
+ first.
20
+
21
+ Assuming you have RubyGems installed, all you have to do is:
22
+
23
+ gem --remote-install copland
24
+
25
+ This will install the latest version of Copland.
26
+
27
+ Copland is also distributed as a Ruby library. It's not as easy to install this way,
28
+ but it works. Simply grab the latest copland package from the website, untar it, and
29
+ install it by typing:
30
+
31
+ ruby setup.rb
32
+
33
+ Or, if you want a little more control over the installation:
34
+
35
+ ruby setup.rb --help
36
+
37
+ This will show you the options that are available to you, and then you can do each stage
38
+ of the installation manually:
39
+
40
+ ruby setup.rb config
41
+ ruby setup.rb setup
42
+ ruby setup.rb install
43
+
44
+ == Manual
45
+
46
+ For more information about Copland, such as an overview and tutorials, see the Copland
47
+ manual at http://copland.rubyforge.org.
48
+
49
+ == Credits
50
+
51
+ Thanks go to:
52
+
53
+ * Matz, for creating Ruby in the first place.
54
+ * Howard Lewis Ship, for the HiveMind Java framework that inspired Copland.
55
+
56
+ == License
57
+
58
+ Copland is copyright (c) 2004 Jamis Buck. It is free software, and may be redistributed
59
+ under the terms of the BSD licence:
60
+
61
+ Redistribution and use in source and binary forms, with or without
62
+ modification, are permitted provided that the following conditions are met:
63
+
64
+ * Redistributions of source code must retain the above copyright notice,
65
+ this list of conditions and the following disclaimer.
66
+
67
+ * Redistributions in binary form must reproduce the above copyright
68
+ notice, this list of conditions and the following disclaimer in the
69
+ documentation and/or other materials provided with the distribution.
70
+
71
+ * The names of its contributors may not be used to endorse or promote
72
+ products derived from this software without specific prior written
73
+ permission.
74
+
75
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
76
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
77
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
78
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
79
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
80
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
81
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
82
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
83
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
84
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
85
+
86
+ The Copland manual and all software used to build it are distributed under the
87
+ Attribution-ShareAlike 1.0 Creative Commons license. Distribute it and modify it all you
88
+ want, but give me credit and distribute your changes under an identical license.
data/doc/manual-html/chapter-1.html ADDED
@@ -0,0 +1,454 @@
1
+ <html>
2
+ <head>
3
+ <title>Copland Manual :: Chapter 1: Introduction</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><strong>
34
+ <a href="chapter-1.html">
35
+ Introduction
36
+ </a>
37
+ </strong> <big>&larr;</big>
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>
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>1. Introduction</h1>
295
+
296
+
297
+
298
+ <h2>
299
+ <a name="s1"></a>
300
+ 1.1. What is Copland?
301
+ </h2>
302
+
303
+
304
+
305
+ <div class="section">
306
+ <p>Copland is an <em>Inversion of Control</em> (IoC) container, written in <a href="http://www.ruby-lang.org">Ruby</a>, for use in Ruby programs. Depending on whether or not the term &#8220;IoC&#8221; means anything at all to you, you can read either the next section (&#8220;Copland <em>sans</em> Buzzwords&#8221;), or the one after it (&#8220;Copland <em>avec</em> Buzzwords&#8221;).</p>
307
+
308
+ <h3>Copland <em>sans</em> Buzzwords</h3>
309
+
310
+ <p>Imagine being able to take all the various pieces of your program and implement them in a vacuum. You just assume that all dependencies will be satisfied at runtime, by properties being set, or parameters being passed to each object&#8217;s constructor. Nowhere in your code do you specify the instantiation of another application component.</p>
311
+
312
+ <p>However, those dependencies and relationships between objects <em>still exist</em>; you&#8217;ve just written your code without any explicit knowledge of them. Somehow, you still need to be able to wire the pieces all together so they work as required in tandem. To put it another way, you need to be able to take your classes and <em>compose</em> them into something greater.</p>
313
+
314
+ <p>Enter Copland.</p>
315
+
316
+ <p>Copland helps you tie the pieces of your application together. Instead of inter-object relationships and dependencies being specified in the code, you feed them into Copland. This makes those relationships easier to modify, since you never have to modify the source code to change them.</p>
317
+
318
+ <p>Copland is named after the American composer <a href="http://www.lucidcafe.com/library/95nov/copland.html">Aaron Copland</a> for a reason. You may or may not have any musical talent, but Copland will give you the ability to compose great &#8220;symphonies of software&#8221; by allowing you to work easily at both extremes of software architecture:</p>
319
+
320
+ <ol>
321
+ <li>It helps you to focus on the implementation of a single class by allowing you to ignore the implementation details of the dependencies of the current class.</li>
322
+ <li>It helps you to focus on the relationships between classes by allowing you to specify those relationships and dependencies as run-time configuration options.</li>
323
+ </ol>
324
+
325
+ <h3>Copland <em>avec</em> Buzzwords</h3>
326
+
327
+ <p>If you are already familiar with IoC, then you either love it or hate it. In the first case, you probably only want to know what features Copland has compared to other IoC containers you&#8217;ve used. In the second case, there&#8217;s probably not much I can say to change your opinion, so I won&#8217;t try.</p>
328
+
329
+ <p>I&#8217;ll save all the meaty discussions for the chapter on Copland&#8217;s design, but here&#8217;s the rundown:</p>
330
+
331
+ <ul>
332
+ <li>Copland is based heavily on the <a href="http://jakarta.apache.org/hivemind">HiveMind</a> IoC container for Java. If you&#8217;ve ever used that one, much of Copland will probably feel very familiar to you.</li>
333
+ <li>Copland allows you to define <em>service points</em>, <em>configuration points</em>, contribute to <em>configuration points</em>, add <em>interceptors</em> to services, add <em>listeners</em> to services, define <em>multicast</em> services, and even make your services web-enabled by using the built-in <span class="caps">SOAP</span> or dRuby interfaces.</li>
334
+ <li>Copland uses <a href="http://www.yaml.org">YAML</a> for its configuration files, instead of <span class="caps">XML</span>. If you&#8217;ve never used <span class="caps">YAML</span>, you&#8217;ll find it surprisingly easy to pick up.</li>
335
+ </ul>
336
+
337
+ <h3>The Buzzwords Themselves</h3>
338
+
339
+ <p>As <a href="http://www.martinfowler.com">Martin Fowler</a> <a href="http://martinfowler.com/articles/injection.html">points out</a>, the term &#8220;Inversion of Control&#8221; is a poorly-chosen one. Still, it is the one that most people know the concept by, so I&#8217;ll use it throughout this document.</p>
340
+
341
+ <p>For more info about IoC, you might try reading the following articles:</p>
342
+
343
+ <ul>
344
+ <li><a href="http://martinfowler.com/articles/injection.html">Inversion of Control Containers and the Dependency Injection pattern</a> (Martin Fowler)</li>
345
+ <li><a href="http://docs.codehaus.org/display/PICO/Inversion+of+Control">Inversion of Control</a> (from the PicoContainer site, another Java-based IoC container)</li>
346
+ <li><a href="http://jakarta.apache.org/hivemind/ioc.html">Inversion of Control</a> (HiveMind&#8217;s take on the subject)</li>
347
+ </ul>
348
+ </div>
349
+
350
+
351
+
352
+ <h2>
353
+ <a name="s2"></a>
354
+ 1.2. Features
355
+ </h2>
356
+
357
+
358
+
359
+ <div class="section">
360
+ <p>Currently, Copland features the following buzzwords:</p>
361
+
362
+ <ul>
363
+ <li>Type 2 IoC (<em>setter injection</em>)</li>
364
+ <li>Type 3 IoC (<em>constructor injection</em>)</li>
365
+ <li><span class="caps">YAML</span>-based descriptor configuration</li>
366
+ <li>Object-, Class-, and Singleton-backed services</li>
367
+ <li>Service factories, with extendable rule-processing engine for defining new factories.</li>
368
+ <li>Interceptors (for adding basic <span class="caps">AOP</span>-like &#8220;pre&#8221; and &#8220;post&#8221; hooks to every method of a service)</li>
369
+ <li>Multicast services, which do nothing themselves except delegate recieved messages to a set of other interested services.</li>
370
+ <li>Event/Listener infrastructure, for notifying services at various points during another service&#8217;s lifecycle.</li>
371
+ <li>dRuby and <span class="caps">SOAP</span> support, in the form of two core services that applications may use to export their services to remote clients.</li>
372
+ </ul>
373
+ </div>
374
+
375
+
376
+
377
+ <h2>
378
+ <a name="s3"></a>
379
+ 1.3. Getting Copland
380
+ </h2>
381
+
382
+
383
+
384
+ <div class="section">
385
+ <h3>Using <a href="http://rubygems.rubyforge.org">RubyGems</a></h3>
386
+
387
+ <p>Installing via the <a href="http://rubygems.rubyforge.org">RubyGems</a> system is trivial&#8212;you just need to make sure that you have RubyGems properly installed. Once RubyGems is installed, make sure you are logged in as a user with permissions to update your local gem repository, and then type:</p>
388
+
389
+ <pre>
390
+ gem install copland
391
+ </pre>
392
+
393
+ <p>Alternatively, you can download the gem file itself (if, for instance, the RubyGems gem repository is down, or hasn&#8217;t been updated with the latest version of Copland). Just go to <a href="http://rubyforge.org/projects/copland">Copland&#8217;s RubyForge project page</a> and download the gem for the latest version. Then, from the command-line, type:</p>
394
+
395
+ <pre>
396
+ gem install path/to/the/file/you/downloaded.gem --local
397
+ </pre>
398
+
399
+ <h3>Manual Installation</h3>
400
+
401
+ <p>If, for whatever reason, RubyGems is not an option for you, you can go to <a href="http://rubyforge.org/projects/copland">Copland&#8217;s RubyForge project page</a> and download the <code>tar.gz</code> file for the latest version of Copland. Then:</p>
402
+
403
+ <ol>
404
+ <li>Unpack the archive. It will extract all files to a new directory under the current directory.</li>
405
+ <li><code>cd</code> to the new directory.</li>
406
+ <li>Make sure you are logged in as a user with permissions to install Ruby libraries. If you are, just type:</li>
407
+ </ol>
408
+
409
+ <pre>
410
+ ruby setup.rb config
411
+ ruby setup.rb setup
412
+ ruby setup.rb install
413
+ </pre>
414
+ </div>
415
+
416
+
417
+
418
+ <h2>
419
+ <a name="s4"></a>
420
+ 1.4. License Information
421
+ </h2>
422
+
423
+
424
+
425
+ <div class="section">
426
+ <p>Copland is currently distrubuted under <a href="http://www.opensource.org/licenses/bsd-license.php">the <span class="caps">BSD</span> license</a>. Versions of Copland prior to 0.6 were released under <a href="http://www.ruby-lang.org/en/LICENSE.txt">the same license as Ruby</a>.</p>
427
+
428
+ <p>This manual (both in <span class="caps">YAML</span> and <span class="caps">HTML</span> formats), as well as the minimal Ruby scripts used to generate it, are distributed under the <a href="http://creativecommons.org">Creative Commons</a> <a href="http://creativecommons.org/licenses/by-sa/2.0">Attribution-ShareAlike</a> license.<br />
429
+ </p>
430
+ </div>
431
+
432
+
433
+
434
+ <h2>
435
+ <a name="s5"></a>
436
+ 1.5. Support
437
+ </h2>
438
+
439
+
440
+
441
+ <div class="section">
442
+ <p>Mailing lists, bug trackers, feature requests, and public forums are available (courtesy of <a href="http://rubyforge.org">RubyForge</a>) at Copland&#8217;s RubyForge project page. Just direct your browser to <a href="http://rubyforge.org/projects/copland">http://rubyforge.org/projects/copland</a>.<br />
443
+ </p>
444
+ </div>
445
+
446
+
447
+
448
+
449
+ </div>
450
+
451
+ </td></tr>
452
+ </table>
453
+ </body>
454
+ </html>