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

copland 0.8.0 → 1.0.0

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-12.html CHANGED

@@ -1,6 +1,6 @@
 <html>
   <head>
-    <title>Copland Manual :: Chapter 12: Listeners and Event Producers</title>
+    <title>Copland Manual :: Chapter 12: Schemas</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#s2">How do they work?</a></li>
+                  <li><a href="chapter-10.html#s1">Log Factory</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>
                 <a href="chapter-11.html">
-                Schemas
+                Service Factories
                 </a>
               <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><strong>
+                <a href="chapter-12.html">
+                Schemas
+                </a>
+                </strong> <big>&larr;</big>
+              <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><strong>
-                <a href="chapter-12.html">
+            <li>
+                <a href="chapter-13.html">
                 Listeners and Event Producers
                 </a>
-                </strong> <big>&larr;</big>
               <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,12 +315,12 @@
         <div id="content">
-          <h1>12. Listeners and Event Producers</h1>
+          <h1>12. Schemas</h1>
    <div class="section">
-     <p>Sometimes, you may have a service that produces events. In terms of a <span class="caps">GUI</span>, you might have a button that emits events liked &#8220;clicked&#8221;, &#8220;mouse over&#8221;, &#8220;mouse out&#8221;, &#8220;mouse down&#8221;, and so forth. Copland provides a framework for indicating that instances of a particular service point should listen for events from instances of another service point.<br />
+     <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>
@@ -304,95 +328,289 @@
      <h2>
        <a name="s1"></a>
-       12.1. Event Producers
+       12.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>
+<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>
+       12.2. Subschemas
      </h2>
    <div class="section">
-     <p>At one end of this functionality is the <em>event producer</em>. Using the above example, this would be the button. It is the service that generates and emits the events.</p>
+     <p>Schemas may be nested, to allow for arbitrarily deep schema &#8220;trees&#8221;. Consider the following example:</p>
+<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
+</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>Any service can be an event producer&#8212;all it requires is that the service implement an <code>#add_listener</code> method by which other services may be added as interested parties. Also, although there is nothing that prevents you from using non-singleton services as event producers, it really only works correctly with services using the <code>singleton</code> and <code>singleton-deferred</code> model.</p>
-	<p>When an event occurs, the producer should notify those registered listeners by invoking a method on them. The method should be named &#8220;on_#{event}&#8221; (where event is the name of the event), and it should accept the producer as the first argument, followed by any number of other arguments (as needed for the given event). The listener method should only be invoked if the listener responds to that method; otherwise, it should be silently skipped.</p>
+     <h2>
+       <a name="s3"></a>
+       12.3. Arrays
+     </h2>
-	<p>Optionally, if a listener does not respond to a specific event, the producer may look for a method called &#8220;on_any_event&#8221;; if the listener responds to that, that method may be invoked instead, with the producer as the first parameter and the event as the second, followed by any additional arguments.</p>
-	<p>To make it easier to create event producers, you can mixin the Copland::EventProducer module into your existing services. It provides several methods, including <code>#add_listener</code> and <code>#fire_event</code>.</p>
+   <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>
 <pre>
-  require 'copland/event-producer'
+  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>
-  class MyProducerService
-    include Copland::EventProducer
+	<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>
-    def click
-      do_something_about_it
-      fire_event :clicked
-    end
+	<p>Given that schema, the following contribution would be valid:</p>
-    def mouse_over
-      do_something_else_about_it
-      fire_event :mouse_over
-    end
-  end
+<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
 </pre>
    </div>
      <h2>
-       <a name="s2"></a>
-       12.2. Listeners
+       <a name="s4"></a>
+       12.4. Named vs. Anonymous Schemas
      </h2>
    <div class="section">
-     <p>Listeners are at the other end of the producer/listener link. As with the event producer, any service can be a listener. It just needs to implement a method for each event that it is interested in, and then indicate (in its service point) that it wants to be registered as a listener of a particular service. Unlike event producers, the listeners can use any service model they like.</p>
+     <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>As described above, the listener methods are named &#8220;on_#{event}&#8221;, where &#8220;event&#8221; is the name of the event to listen to. Alternatively, a listener may declare a method called &#8220;on_any_event&#8221;, which will be called for any event that does not have an explicit listener method declared for.</p>
+	<p>To name a schema, just add a <code>name</code> element at the same level as the <code>definition</code> element:</p>
 <pre>
-  class MyListenerService
-    def on_click( producer, *args )
-      puts "Argh! It was clicked!"
-    end
-    def on_any_event( producer, event, *args )
-      puts "Something happened: #{event}"
-    end
-  end
+  MoviesILike:
+    type: list
+    schema:
+      name: MovieDefinition
+      definition:
+        ...
 </pre>
-	<p>To register interest in the producer, use the <code>listen-to</code> element when defining the service point. This element expects an array of service point names. Every time the service point is instantiated, the list of <code>listen-to</code> elements will be processed and the new service will be added to each of those service points in turn, as a listener:</p>
+	<p>Then, you can reuse the schema by putting the schema name after the <code>schema</code> element, instead of a hash:</p>
 <pre>
-  service-points:
+  MoviesIHate:
+    type: list
+    schema: MovieDefinition
+</pre>
-    Producer:
-      implementor: MyProducerService
+	<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>
-    Listener:
-      implementor: MyListenerService
-      listen-to:
-        - Producer
+<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>
    </div>
      <h2>
-       <a name="s3"></a>
-       12.3. The Registry as an Event Producer
+       <a name="s5"></a>
+       12.5. Extending Schemas
+     </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>
+<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>
+   </div>
+     <h2>
+       <a name="s6"></a>
+       12.6. Limitations
      </h2>
    <div class="section">
-     <p>Currently, Copland only comes with one event producer built in&#8212;the registry itself. Every time you instantiate a registry, it adds itself to itself as the &#8220;copland.Registry&#8221; service. When the registry is shutdown, it emits a <code>:registry_shutdown</code> event to all of its listeners.</p>
+     <p>The existing schema implementation is sufficient for most purposes, but it has some limitations:</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>Thus, if you have a service that you want to be able to do some cleanup when the registry is being shutdown, you can have that service listen to &#8220;copland.Registry&#8221;, and implement a listener method called <code>on_registry_shutdown</code> (or <code>on_any_event</code>).</p>
+	<p>For most purposes, however, it is sufficient.</p>
    </div>