RubyGems - copland - Versions diffs - 0.8.0 → 1.0.0 - Mend

copland 0.8.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (50) hide show

data/doc/manual-html/chapter-1.html +227 -36
data/doc/manual-html/chapter-10.html +155 -82
data/doc/manual-html/chapter-11.html +90 -267
data/doc/manual-html/chapter-12.html +289 -71
data/doc/manual-html/chapter-13.html +430 -0
data/doc/manual-html/chapter-2.html +45 -21
data/doc/manual-html/chapter-3.html +45 -21
data/doc/manual-html/chapter-4.html +45 -21
data/doc/manual-html/chapter-5.html +45 -21
data/doc/manual-html/chapter-6.html +49 -21
data/doc/manual-html/chapter-7.html +45 -21
data/doc/manual-html/chapter-8.html +66 -26
data/doc/manual-html/chapter-9.html +48 -24
data/doc/manual-html/index.html +54 -22
data/doc/manual-html/manual.css +12 -0
data/doc/manual-html/tutorial-1.html +45 -21
data/doc/manual-html/tutorial-2.html +45 -21
data/doc/manual-html/tutorial-3.html +45 -21
data/doc/manual-html/tutorial-4.html +45 -21
data/doc/manual-html/tutorial-5.html +45 -21
data/doc/manual/manual.css +12 -0
data/doc/manual/manual.rb +1 -1
data/doc/manual/manual.yml +426 -20
data/doc/packages/copland.html +41 -9
data/doc/packages/copland.lib.html +36 -8
data/doc/packages/copland.remote.html +46 -10
data/doc/packages/copland.webrick.html +16 -65
data/doc/packages/index.html +1 -1
data/doc/presentation/copland.mgp +1083 -0
data/doc/presentation/to_html.rb +52 -0
data/lib/copland/configuration-point/common.rb +32 -1
data/lib/copland/configuration/yaml/service-point.rb +10 -1
data/lib/copland/log-factory.rb +28 -12
data/lib/copland/logger.rb +155 -0
data/lib/copland/models/singleton.rb +8 -2
data/lib/copland/package.rb +32 -14
data/lib/copland/service-point.rb +7 -0
data/lib/copland/thread.rb +104 -0
data/lib/copland/utils.rb +10 -3
data/lib/copland/version.rb +2 -2
data/test/configuration/yaml/tc_service-point-processor.rb +8 -0
data/test/custom-logger.yml +2 -1
data/test/impl/tc_logging-interceptor.rb +12 -12
data/test/logger.yml +1 -1
data/test/mock.rb +2 -0
data/test/tc_logger.rb +19 -6
data/test/tc_package.rb +25 -0
data/test/tc_queryable-mutex.rb +75 -0
data/test/tc_registry.rb +8 -4
metadata +9 -2

data/doc/manual-html/chapter-11.html CHANGED

@@ -1,6 +1,6 @@
 <html>
   <head>
-    <title>Copland Manual :: Chapter 11: Schemas</title>
+    <title>Copland Manual :: Chapter 11: Service Factories</title>
     <link type="text/css" rel="stylesheet" href="manual.css" />
   </head>
@@ -14,8 +14,8 @@
           </div>
         </td><td valign='middle' align='right'>
           <div class="info">
-            Copland Version: <strong>0.8.0</strong><br />
-            Manual Last Updated: <strong>2004-09-27 03:37 GMT</strong>
+            Copland Version: <strong>1.0.0</strong><br />
+            Manual Last Updated: <strong>2004-10-12 02:22 GMT</strong>
           </div>
         </td></tr>
       </table>
@@ -39,13 +39,21 @@
                   <li><a href="chapter-1.html#s1">What is Copland?</a></li>
-                  <li><a href="chapter-1.html#s2">Features</a></li>
+                  <li><a href="chapter-1.html#s2">What Can Copland Do For Me?</a></li>
-                  <li><a href="chapter-1.html#s3">Getting Copland</a></li>
+                  <li><a href="chapter-1.html#s3">Copland <em>sans</em> Buzzwords</a></li>
-                  <li><a href="chapter-1.html#s4">License Information</a></li>
+                  <li><a href="chapter-1.html#s4">Copland <em>avec</em> Buzzwords</a></li>
-                  <li><a href="chapter-1.html#s5">Support</a></li>
+                  <li><a href="chapter-1.html#s5">The Buzzwords Themselves</a></li>
+                  <li><a href="chapter-1.html#s6">Features</a></li>
+                  <li><a href="chapter-1.html#s7">Getting Copland</a></li>
+                  <li><a href="chapter-1.html#s8">License Information</a></li>
+                  <li><a href="chapter-1.html#s9">Support</a></li>
               </ol>
             </li>
@@ -149,7 +157,9 @@
                   <li><a href="chapter-8.html#s1">Descriptor Syntax</a></li>
-                  <li><a href="chapter-8.html#s2">DefaultSymbolSource</a></li>
+                  <li><a href="chapter-8.html#s2">FactoryDefaults</a></li>
+                  <li><a href="chapter-8.html#s3">ApplicationDefaults</a></li>
               </ol>
             </li>
@@ -166,54 +176,68 @@
             <li>
                 <a href="chapter-10.html">
-                Service Factories
+                Logging
                 </a>
               <ol type="1">
-                  <li><a href="chapter-10.html#s1">Schemas</a></li>
+                  <li><a href="chapter-10.html#s1">Log Factory</a></li>
-                  <li><a href="chapter-10.html#s2">How do they work?</a></li>
-                  <li><a href="chapter-10.html#s3">BuilderFactory</a></li>
+                  <li><a href="chapter-10.html#s2">Configuration</a></li>
               </ol>
             </li>
             <li><strong>
                 <a href="chapter-11.html">
-                Schemas
+                Service Factories
                 </a>
                 </strong> <big>&larr;</big>
               <ol type="1">
-                  <li><a href="chapter-11.html#s1">Basic Format</a></li>
+                  <li><a href="chapter-11.html#s1">Schemas</a></li>
+                  <li><a href="chapter-11.html#s2">How do they work?</a></li>
+                  <li><a href="chapter-11.html#s3">BuilderFactory</a></li>
+              </ol>
+            </li>
+            <li>
+                <a href="chapter-12.html">
+                Schemas
+                </a>
+              <ol type="1">
+                  <li><a href="chapter-12.html#s1">Basic Format</a></li>
-                  <li><a href="chapter-11.html#s2">Subschemas</a></li>
+                  <li><a href="chapter-12.html#s2">Subschemas</a></li>
-                  <li><a href="chapter-11.html#s3">Arrays</a></li>
+                  <li><a href="chapter-12.html#s3">Arrays</a></li>
-                  <li><a href="chapter-11.html#s4">Named vs. Anonymous Schemas</a></li>
+                  <li><a href="chapter-12.html#s4">Named vs. Anonymous Schemas</a></li>
-                  <li><a href="chapter-11.html#s5">Extending Schemas</a></li>
+                  <li><a href="chapter-12.html#s5">Extending Schemas</a></li>
-                  <li><a href="chapter-11.html#s6">Limitations</a></li>
+                  <li><a href="chapter-12.html#s6">Limitations</a></li>
               </ol>
             </li>
             <li>
-                <a href="chapter-12.html">
+                <a href="chapter-13.html">
                 Listeners and Event Producers
                 </a>
               <ol type="1">
-                  <li><a href="chapter-12.html#s1">Event Producers</a></li>
+                  <li><a href="chapter-13.html#s1">Event Producers</a></li>
-                  <li><a href="chapter-12.html#s2">Listeners</a></li>
+                  <li><a href="chapter-13.html#s2">Listeners</a></li>
-                  <li><a href="chapter-12.html#s3">The Registry as an Event Producer</a></li>
+                  <li><a href="chapter-13.html#s3">The Registry as an Event Producer</a></li>
               </ol>
             </li>
@@ -291,302 +315,101 @@
         <div id="content">
-          <h1>11. Schemas</h1>
+          <h1>11. Service Factories</h1>
    <div class="section">
-     <p>&#8220;Schemas&#8221; are the mechanism by which you can restrict what values are contributed to configuration points, or which parameters are acceptable to a service constructed via a factory service.<br />
-</p>
-   </div>
+     <p>Sometimes it requires a little more effort (or a lot more effort) to instantiate and initialize a service than simply calling <code>#new</code> on it&#8217;s associated class. In such cases, you need to rely on a <em>service factory</em> to instantiate the service.</p>
+	<p>A service factory is just a regular service as far as Copland is concerned. It is declared in the usual way. However, a service that will be used as a service factory must implement at least one method: <code>#create_instance</code>. This method should accept two parameters, the <em>service point</em> to instantiate, and the <em>parameters</em> associated with this instantiation. (The <code>parameters</code> parameter will always be a hash.)</p>
-     <h2>
-       <a name="s1"></a>
-       11.1. Basic Format
-     </h2>
-   <div class="section">
-     <p>In <span class="caps">YAML</span> terminology, a schema is simply a map that follows a special format. Consider the following configuration point:</p>
+	<p>Here is an example that implements a trivial service factory:</p>
 <pre>
-  MyConfigurationPoint:
-    type: map
-    schema:
-      definition:
-        user.name:
-          type: string
-          required: true
-        home.directory:
-          type: string
-        user.groups:
-          type: array
-</pre>
-	<p>This configuration point is a map that only allows three keys: <code>user.name</code>, <code>home.directory</code>, and <code>user.groups</code>. Any contribution made to this configuration point <em>must not</em> contain any keys other than these values. And since the <code>user.name</code> key is marked as required, any contribution to this configuration point <em>must</em> contain at least that key.</p>
-	<p>Note the type definitions as well. The recognized types are:</p>
-	<ul>
-	<li><code>any</code></li>
-		<li><code>array</code></li>
-		<li><code>configuration</code></li>
-		<li><code>integer</code></li>
-		<li><code>log</code></li>
-		<li><code>hash</code></li>
-		<li><code>real</code></li>
-		<li><code>service</code></li>
-		<li><code>string</code></li>
-	</ul>
-	<p>If the type is left out, it defaults to <code>any</code>. If a value is contributed to that key that is not of the required type, a validation error results.</p>
-	<p>Note that schemas may be applied to service points as well, in identical fashion to that of configuration points. (That is to say, they are introduced by the <code>schema</code> descriptor element.) In that case, the schema applies to the parameters of any service point that uses this service point as its factory service.</p>
-   </div>
-     <h2>
-       <a name="s2"></a>
-       11.2. Subschemas
-     </h2>
+  class ExampleServiceFactory
-   <div class="section">
-     <p>Schemas may be nested, to allow for arbitrarily deep schema &#8220;trees&#8221;. Consider the following example:</p>
+    def create_instance( point, parms )
+      return { :point =&gt; point,
+               :parms =&gt; parms }
+    end
-<pre>
-  MyConfigurationPoint:
-    type: map
-    schema:
-      definition:
-        user.name:
-          type: string
-          required: true
-        home.directory:
-          type: string
-        user.groups:
-          type: array
-        user.address:
-          definition:
-            line1:
-              type: string
-            line2:
-              type: string
-            city:
-              type: string
-            state:
-              type: string
-            zip:
-              type: string
+  end
 </pre>
-	<p>In this case, the <code>user.address</code> element of the schema is itself <em>another schema</em>. That is to say, any element that it matches must be a hash, which may be empty, but which may contain no keys other than those specified (<code>line1</code>, <code>line2</code>, <code>city</code>, <code>state</code>, and <code>zip</code>).</p>
-	<p>If you specify a subschema definintion (via the <code>definition</code> keyword), and the same element is of any type other than <code>hash</code> or <code>array</code>, you&#8217;ll get an error. You cannot used schema&#8217;s to validate any other type of data. (Arrays are a special case&#8212;see the next section.)</p>
-   </div>
+	<p>This service would be introduced into Copland via the following package descriptor:</p>
+<pre>
+  ---
+  id: example
-     <h2>
-       <a name="s3"></a>
-       11.3. Arrays
-     </h2>
+  service-points:
+    ExampleServiceFactory:
+      implementor: some/file/ExampleServiceFactory
+</pre>
-   <div class="section">
-     <p>When you specify a schema for an array (or for a configuration point of type <code>list</code>), the schema will be applied to every element of any array that is contributed. For example, consider this:</p>
+	<p>And it would be employed like this:</p>
 <pre>
-  MoviesILike:
-    type: list
-    schema:
-      definition:
-        name:
-          type: string
-          required: true
-        genre:
-          type: string
-        actors:
-          type: array
-          definition:
-            name:
-              type: string
-              required: true
-            gender:
-              type: string
-            birthdate:
-              type: string
-</pre>
+  ---
+  id: demo
-	<p>This configuration point is a <code>list</code>. Every element that is contributed to it must conform to the given schema. Note, too, that the <code>actors</code> element of the schema expects an array, and that each element of <em>that</em> array must conform to the given subschema.</p>
+  service-points:
-	<p>Given that schema, the following contribution would be valid:</p>
-<pre>
-  contributions:
-    MoviesILike:
-      - name: Twelve Angry Men
-        genre: Drama
-        actors:
-          - name: Henry Fonda
-            gender: male
-            birthdate: 16 May 1905
-          - name: Jack Klugman
-            birthdate: 27 Apr 1922
-          - name: Ed Binns
-          - name: John Fiedler
-      - name: Lawrence of Arabia
-        actors:
-          - name: Peter O'Toole
-          - name: Alec Guinness
-            birthdate: 2 Apr 1914
-      - name: Remains of the Day
+    ExampleService:
+      implementor:
+        factory: example.ExampleServiceFactory
 </pre>
+	<p>This service factory, when used to instantiate a service, would always return a new Hash object consisting of the service point and its parameters. Thus, the <code>ExampleService</code> service point would, when instantiated, always consist of a hash containing its own service point, and any parameters that were given when it was instantiated (none, in this case). Not a very useful service factory, but it demonstrates what it ought to do.<br />
+</p>
    </div>
      <h2>
-       <a name="s4"></a>
-       11.4. Named vs. Anonymous Schemas
+       <a name="s1"></a>
+       11.1. Schemas
      </h2>
    <div class="section">
-     <p>The schemas that have been shown so far have been <em>anonymous</em>. This is fine for schemas that are very specific and have a very special purpose. However, sometimes, you want several configuration points of service points to have the same schema. To accomplish this, you need to give your schemas names.</p>
-	<p>Named schemas are owned by the package in which they are defined, but once named they may be used in any package (just like service points and configuration points).</p>
-	<p>To name a schema, just add a <code>name</code> element at the same level as the <code>definition</code> element:</p>
-<pre>
-  MoviesILike:
-    type: list
-    schema:
-      name: MovieDefinition
-      definition:
-        ...
-</pre>
-	<p>Then, you can reuse the schema by putting the schema name after the <code>schema</code> element, instead of a hash:</p>
-<pre>
-  MoviesIHate:
-    type: list
-    schema: MovieDefinition
-</pre>
-	<p>This second configuration point will reuse the <code>MovieDefinition</code> schema.  Note that you can specify an existing schema (or name a schema) at any level of a schema definition:</p>
-<pre>
-  MoviesILike:
-    type: list
-    schema:
-      name: MovieDefinition
-      definition:
-        name:
-          type: string
-          required: true
-        genre:
-          type: string
-        actors:
-          name: ActorDefinition
-          type: array
-          definition:
-            name:
-              type: string
-              required: true
-            gender:
-              type: string
-            birthdate:
-              type: string
-  MoviesIHate:
-    type: list
-    schema: MovieDefinition
-  FavoriteActors:
-    type: list
-    schema: ActorDefinition
-  PartiesAttended:
-    type: list
-    schema:
-      definition:
-        place:
-          type: string
-        host:
-          type: string
-        attendees: ActorDefinition
-</pre>
+     <p>As mentioned in the chapter on service points, a service point may be associated with a <em>schema</em>. More will be said on schemas (and specifically, on their formats) in the next chapter, but suffice it to say here that the schema allows a service point to specify what parameters it accepts when invoked as a factory service.<br />
+</p>
    </div>
      <h2>
-       <a name="s5"></a>
-       11.5. Extending Schemas
+       <a name="s2"></a>
+       11.2. How do they work?
      </h2>
    <div class="section">
-     <p>Sometimes it happens that you want to create a schema that is <em>almost</em> like an existing schema, but adds one or two new elements. You can do this in Copland by <em>extending</em> the existing schema:</p>
+     <p>When you specify a factory service as the implementor of another service, Copland automatically marks that service point as needing a <em>complex instantiator</em>. Thus, when it comes time to instantiate the service point, the parameters are collected, and if the factory has a schema, the parameters are validated against that schema. Then, the parameters are preprocessed (to translate values to their appropriate and expected types), and the factory&#8217;s <code>#create_instance</code> method is called. The result of that call is then treated as the new service.</p>
-<pre>
-  People:
-    type: list
-    schema:
-      name: PersonSchema
-      definition:
-        name:
-          required: true
-          type: string
-        gender:
-          required: true
-          type: string
-  Employees:
-    type: list
-    schema:
-      name: EmployeeSchema
-      extend: PersonSchema
-      definition:
-        department:
-          required: true
-          type: string
-</pre>
-	<p>In the above instance, the &#8220;EmployeeSchema&#8221; is exactly like the PersonSchema, except it adds a &#8220;department&#8221; key.</p>
+	<p>Contrast this with the <em>simple instantiator</em>. When the simple instantiator is used, all it does (more or less) is invoke <code>#new</code> on the named class and return the result. The existence of factory services allows for much more complex (and powerful) behavior.<br />
+</p>
    </div>
      <h2>
-       <a name="s6"></a>
-       11.6. Limitations
+       <a name="s3"></a>
+       11.3. BuilderFactory
      </h2>
    <div class="section">
-     <p>The existing schema implementation is sufficient for most purposes, but it has some limitations:</p>
+     <p>Copland comes with one predefined factory service: <code>copland.BuilderFactory</code>. With this factory you can implement most of the more common types of services. (There are always special cases, though&#8212;the <code>copland.lib</code>, <code>copland.remote</code> and <code>copland.webrick</code> libraries all define additional factory services for specialized uses.)</p>
-	<ul>
-	<li>You cannot specify a format for a non-hash value.</li>
-		<li>You cannot specify whether a subschema that reuses an existing schema is required or not.</li>
-		<li>You cannot enforce the constraint &#8220;any one of a set of keys is required.&#8221; The schema subsystem only understands a single key being required or not.</li>
-	</ul>
-	<p>For most purposes, however, it is sufficient.</p>
+	<p>The BuilderFactory allows you to not only instantiate a class, but to specify constructor parameters and set properties on the new object. It also allows you to specify methods that should be invoked in order to initialize a service. It is by this means that the &#8220;dependency injection&#8221; aspect of Copland comes into play.<br />
+</p>
    </div>