copland 0.8.0 → 1.0.0

data/doc/manual-html/chapter-1.html

@@ -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">
+                Logging
+                </a>
+                
+              <ol type="1">
+                
+                  <li><a href="chapter-10.html#s1">Log Factory</a></li>
+                
+                  <li><a href="chapter-10.html#s2">Configuration</a></li>
+                
+              </ol>
+            </li>
+          
+            <li>
+                <a href="chapter-11.html">
                 Service Factories
                 </a>
                 
               <ol type="1">
                 
-                  <li><a href="chapter-10.html#s1">Schemas</a></li>
+                  <li><a href="chapter-11.html#s1">Schemas</a></li>
                 
-                  <li><a href="chapter-10.html#s2">How do they work?</a></li>
+                  <li><a href="chapter-11.html#s2">How do they work?</a></li>
                 
-                  <li><a href="chapter-10.html#s3">BuilderFactory</a></li>
+                  <li><a href="chapter-11.html#s3">BuilderFactory</a></li>
                 
               </ol>
             </li>
           
             <li>
-                <a href="chapter-11.html">
+                <a href="chapter-12.html">
                 Schemas
                 </a>
                 
               <ol type="1">
                 
-                  <li><a href="chapter-11.html#s1">Basic Format</a></li>
+                  <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>
@@ -303,11 +327,160 @@
    
 
    <div class="section">
-     <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>
+     <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. In a nutshell, it allows you to simplify the instantiation and initialization of your classes.<br />
+</p>
+   </div>
+
+
+
+     <h2>
+       <a name="s2"></a>
+       1.2. What Can Copland Do For Me?
+     </h2>
+
+   
+
+   <div class="section">
+     <p>So, what can Copland do for you? Ultimately, it can reduce the amount of code that you have to write, simplifying many common programming tasks for you. This has the two-fold benefit of both decreasing application development time, and of decreasing the effort needed to maintain your application.</p>
+
+	<p>But what, <em>specifically</em>, can Copland do for you?</p>
+
+	<p>Try these on for size:</p>
+
+	<ul>
+	<li><a href="#logmethods">Log Method Execution</a></li>
+		<li><a href="#refsvc">Reference Another Service</a></li>
+		<li><a href="#svcconfig">Service Configuration</a></li>
+		<li><a href="#unittest">Unit Testing</a></li>
+		<li><a href="#lifecycle">Lifecycle Management</a></li>
+	</ul>
+
+	<p>(Thanks to Howard Lewis Ship for his <a href="http://jakarta.apache.org/hivemind">HiveMind</a> documentation, from which most of the above bullet points were adapted.)</p>
+
+	<h3>A. Log Method Execution <a name="logmethods"></a></h3>
+
+	<p>Copland has an integrated logging framework, and the ability to log execution trace information <em>without modifying a single line of your code</em>. This means that you can easily see what methods get called, with what arguments, and what the return values are, all without having to add a single line of logging code to your classes.</p>
+
+	<p>Consider the following code, demonstrating how this would be done <em>without</em> Copland:</p>
+
+<pre>
+  def foo( arg1, arg2 )
+    @log.debug( "in foo with #{arg1} and #{arg2}" ) if @log.debug?
+    ...
+    result = the_result_of_the_method
+    @log.debug( "finishing foo with #{result}" ) if @log.debug
+    return result
+  rescue Exception =&gt; e
+    @log.debug( "foo raised exception #{e.message} (#{e.class})" ) if @log.debug?
+    raise
+  end
+</pre>
+
+	<p>Now, multiply that by the number of methods in your class&#8230; the logging messages quickly overpower the rest of the code, and detract from the flow of your program. This makes your program harder to debug, test, and maintain.</p>
+
+	<p>Now, consider the same method using Copland&#8217;s integrated logging framework&#8230;</p>
+
+<pre>
+  def foo( arg1, arg2 )
+    ...
+    return the_result_of_the_method
+  end
+</pre>
+
+	<p>Uh, huh. That&#8217;s right. <em>There&#8217;s no explicit logging code in there.</em> Instead, you just tell Copland that the methods of the class should be logged, and away it goes. This has the added benefit of allowing your objects to be unit tested, without spewing log messages everywhere. (Look for the tutorial about &#8220;Logging Interceptors&#8221; for an actual demonstration of how to do this.)</p>
+
+	<h3>B. Reference Another Service <a name="refsvc"></a></h3>
+
+	<p>Invariably in a large application services will reference other services. This is typically accomplished through something like this:</p>
+
+<pre>
+  def foo( parms )
+    @service ||= lookup_service
+    @service.do_something( parms )
+  end
+</pre>
+
+	<p>Whether the lookup is done lazily, as shown above, or when the class is first instantiated is irrelevant. The point is that you either have to implement a bunch of code to look up a service based on some criteria, or you hard code the class of the service (which creates tight coupling and makes things like unit testing harder).</p>
+
+	<p>With Copland, you just declare a setter for the service, and then tell Copland that the class depends on the other service:</p>
+
+<pre>
+  attr_writer :service
+
+  def foo( parms )
+    @service.do_something( parms )
+  end
+</pre>
+
+	<p>Then, when your service is instantiated, Copland will automatically look for, instantiate, and set the dependencies for you. This makes for cleaner code, and looser coupling between services.</p>
+
+	<h3>C. Service Configuration <a name="svcconfig"></a></h3>
+
+	<p>Often, a large application or library will need some way to allow different classes to be configured at runtime. Whether you have a factory class that requires the available producable classes to register themselves with it, or whether you just want to allow third-parties to be able to extend your application, you wind up implementing some form of decentralized configuration.</p>
+
+	<p>Copland allows you to define <em>configuration points</em>, which any package may then contribute values to. Furthermore, just as services can reference other services, services can reference configuration points, and Copland will manage them just like any other dependency.</p>
+
+	<p>See the tutorial about &#8220;Configuration Points&#8221; for an example of this feature.</p>
+
+	<h3>D. Unit Testing <a name="unittest"></a></h3>
+
+	<p>Large applications can prove troublesome to unit test exhaustively, especially if there is any kind of tight coupling between components. Such coupling of components can make it difficult to test them separately.</p>
+
+	<p>Copland, by its very nature, encourages loose coupling of components. Also, because dependencies are never instantiated in code, but are instead accepted via setters or constructor arguments, it is trivial to replace those dependencies with mock objects at unit test time.</p>
+
+	<p>Consider this tightly coupled example:</p>
+
+<pre>
+  def foo( args )
+    @some_dependency ||= MyNewDependency.new
+    @some_dependency.do_something(args)
+  end
+</pre>
+
+	<p>It is impossible to test the method <code>#foo</code> without also testing the MyNewDependency class. However, if the <code>@some_dependency</code> object is made a property that is set externally, you can replace it at test time with a blank:</p>
+
+<pre>
+  attr_writer :some_dependency
+
+  def foo( args )
+    @some_dependency.do_something( args )
+  end
+</pre>
+
+	<p>The unit test would become something like this:</p>
+
+<pre>
+  def test_foo
+    @obj.some_dependecy = MyMockDependency.new
+    @obj.foo( args )
+    assert @obj.is_in_some_state
+  end
+</pre>
+
+	<h3>E. Lifecycle Management <a name="lifecycle"></a></h3>
 
-	<h3>Copland <em>sans</em> Buzzwords</h3>
+	<p>Singleton objects are a fact of life in complex systems. The singleton design pattern is powerful and useful. However, using the Singleton mixin, or declaring methods at the class level, can make your code difficult to unit test since the state of such objects cannot be easily reset.</p>
 
-	<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>
+	<p>Copland has a solution. You can tell Copland to treat a service as either a <em>prototype</em> service (meaning it will be instantiated every time you ask for it, like calling <code>#new</code>), or a <em>singleton</em> service (meaning it will only be instantiated once, and the same instance will be returned for subsequent requests).</p>
+
+	<p>Your object is still just a plain ol&#8217; ordinary Ruby object, but Copland has effectively transformed it into a singleton. This means you can unit test it as if it were nothing special, but when it is used in your application it will act like a singleton.</p>
+
+	<p>Lifecycle management also means that you can control <em>when</em> a service is instantiated. The <em>prototype</em> and <em>singleton</em> models will always be instantiated as soon as they are requested. Sometimes, though, you don&#8217;t want that&#8212;you&#8217;d like the instantiation to be deferred as long as possible.</p>
+
+	<p>With Copland, you can indicate that a service should use deferred instantiation. This will cause the service to not actually be instantiated until a method is actually invoked on it. Using this model, you can have services depend on themselves, or other forms of cyclical dependencies.</p>
+   </div>
+
+
+
+     <h2>
+       <a name="s3"></a>
+       1.3. Copland <em>sans</em> Buzzwords
+     </h2>
+
+   
+
+   <div class="section">
+     <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>
 
 	<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>
 
@@ -321,10 +494,19 @@
 	<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>
 		<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>
 	</ol>
+   </div>
 
-	<h3>Copland <em>avec</em> Buzzwords</h3>
 
-	<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>
+
+     <h2>
+       <a name="s4"></a>
+       1.4. Copland <em>avec</em> Buzzwords
+     </h2>
+
+   
+
+   <div class="section">
+     <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>
 
 	<p>I&#8217;ll save all the meaty discussions for the chapter on Copland&#8217;s design, but here&#8217;s the rundown:</p>
 
@@ -333,10 +515,19 @@
 		<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>
 		<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>
 	</ul>
+   </div>
+
+
+
+     <h2>
+       <a name="s5"></a>
+       1.5. The Buzzwords Themselves
+     </h2>
 
-	<h3>The Buzzwords Themselves</h3>
+   
 
-	<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>
+   <div class="section">
+     <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>
 
 	<p>For more info about IoC, you might try reading the following articles:</p>
 
@@ -350,8 +541,8 @@
 
 
      <h2>
-       <a name="s2"></a>
-       1.2. Features
+       <a name="s6"></a>
+       1.6. Features
      </h2>
 
    
@@ -375,8 +566,8 @@
 
 
      <h2>
-       <a name="s3"></a>
-       1.3. Getting Copland
+       <a name="s7"></a>
+       1.7. Getting Copland
      </h2>
 
    
@@ -416,8 +607,8 @@
 
 
      <h2>
-       <a name="s4"></a>
-       1.4. License Information
+       <a name="s8"></a>
+       1.8. License Information
      </h2>
 
    
@@ -432,8 +623,8 @@
 
 
      <h2>
-       <a name="s5"></a>
-       1.5. Support
+       <a name="s9"></a>
+       1.9. Support
      </h2>
 
    

data/doc/manual-html/chapter-10.html

@@ -1,6 +1,6 @@
 <html>
   <head>
-    <title>Copland Manual :: Chapter 10: Service Factories</title>
+    <title>Copland Manual :: Chapter 10: Logging</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><strong>
                 <a href="chapter-10.html">
-                Service Factories
+                Logging
                 </a>
                 </strong> <big>&larr;</big>
               <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>
                 <a href="chapter-11.html">
+                Service Factories
+                </a>
+                
+              <ol type="1">
+                
+                  <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-11.html#s1">Basic Format</a></li>
+                  <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,101 +315,150 @@
 
         <div id="content">
 
-          <h1>10. Service Factories</h1>
+          <h1>10. Logging</h1>
 
 
 
    <div class="section">
-     <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>
-
-	<p>Here is an example that implements a trivial service factory:</p>
-
-<pre>
-  class ExampleServiceFactory
-
-    def create_instance( point, parms )
-      return { :point =&gt; point,
-               :parms =&gt; parms }
-    end
-
-  end
-</pre>
+     <p>Copland has an integrated logging system based on a slight variation of Ruby&#8217;s own &#8220;logger&#8221; library. In addition to the features of that library, Copland&#8217;s logging system provides:</p>
 
-	<p>This service would be introduced into Copland via the following package descriptor:</p>
+	<ul>
+	<li>A logger factory for creating shared logger instances</li>
+		<li><span class="caps">YAML</span>-based configuration of the factory</li>
+		<li>Customizable message formatting</li>
+	</ul>
+   </div>
 
-<pre>
-  ---
-  id: example
 
-  service-points:
 
-    ExampleServiceFactory:
-      implementor: some/file/ExampleServiceFactory
-</pre>
+     <h2>
+       <a name="s1"></a>
+       10.1. Log Factory
+     </h2>
 
-	<p>And it would be employed like this:</p>
+   
 
-<pre>
-  ---
-  id: demo
+   <div class="section">
+     <p>Each registry instance has its own instance of <code>Copland::LogFactory</code>. This provides a way to map a name to a logger instance, and allows each service point (for example) to have its own logger instance. This allows various logger settings to be tweaked <em>per service-point</em>.</p>
 
-  service-points:
+	<p>For example, if I want debugging information to be logged for one service point, but not for another, I can specify the logging priority level for the one service point to include debug messages, and have such messages excluded for the other service point.</p>
 
-    ExampleService:
-      implementor:
-        factory: example.ExampleServiceFactory
-</pre>
+	<p>The log factory allows default values to be set for the priority level, date format string, and message format string, which will be applied to any logger that does not have a specific value set for those values. The log factory also allows configuration of the IO device to log to, the filename to log to, and various other (Logger-specific) data items (see the <span class="caps">API</span> documentation for <code>Copland::LogFactory</code> for more information).</p>
 
-	<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>If you ever need to access the current log factory instance, you can get it from the registry as the <code>copland.LogFactory</code> service.<br />
 </p>
    </div>
 
 
 
      <h2>
-       <a name="s1"></a>
-       10.1. Schemas
+       <a name="s2"></a>
+       10.2. Configuration
      </h2>
 
    
 
    <div class="section">
-     <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>
+     <p>There are three ways to configure loggers. The first is programmatically, manually tweaking each log instance directly. The second is to pass configuration options to the registry itself when it is built, and the third is to use a configuration file.</p>
 
+	<h3>Programmatic Configuration</h3>
 
+	<p>To programmatically configure a logger, just obtain a handle to a logger instance and then tweak it via the accessor methods of the logger:</p>
 
-     <h2>
-       <a name="s2"></a>
-       10.2. How do they work?
-     </h2>
+<pre>
+  factory = registry.service( "copland.LogFactory" )
+  log = factory.get( "some.log.name" )
 
-   
+  # Standard Logger attributes
+  log.level = Logger::INFO
+  log.progname = "different.log.name" 
+  log.datetime_format = "%Y%m%d" 
 
-   <div class="section">
-     <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>
+  # Extended Logger attributes (provided by Copland)
+  log.message_format = "[%-5p] %d %c: %m" 
+</pre>
 
-	<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>
+	<p><em>Note:</em> programmatically changing the logger <code>progname</code> does not change the name by which the logger is known to the factory!</p>
 
+	<p>In general, programmatic tweaking of the logger attributes as demonstrated above is not going to be the best way to do it. First of all, it is tedious, and bug prone. Secondly, it is difficult to know where the best place to do such work is, since you need to set those attributes before any other service tries to access that log.</p>
 
+	<h3>Configuration via <code>Registry.build</code></h3>
 
-     <h2>
-       <a name="s3"></a>
-       10.3. BuilderFactory
-     </h2>
+	<p>The second approach is to pass logger configuration options to <code>Registry.build</code>, when you create a registry instance:</p>
 
-   
+<pre>
+  registry = Copland::Registry.build(
+    :log_device =&gt; STDOUT,
+    :log_default_level =&gt; Logger::INFO,
+    ...
+  )
+</pre>
 
-   <div class="section">
-     <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>
+	<p>This gives you much greater flexibility than the previous approach, since it allows you to specify a greater array of options. The allowed options are:</p>
+
+	<table class="list">
+		<tr>
+			<td style="vertical-align:top;"><code>:log_config_file</code></td>
+			<td>This is the name of the configuration file to use to configure the log factory. It defaults to &#8220;logger.yml&#8221;. (See the next section for more information.)</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:log_device</code></td>
+			<td>This is the <span class="caps">IO </span>(or pseudo-IO) object to write log messages to. If this option is specified, <code>:log_filename</code> must not be specified (and vice versa). This allows you to log messages to arbitrary IO streams.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:log_filename</code></td>
+			<td>This is the name of the file to write log messages to. If this option is specified, <code>:log_device</code> must not be specified (and vice versa). This defaults to &#8221;./copland.log&#8221;.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:log_roll_age</code></td>
+			<td>This specifies the number of days before the log should be rolled. (This option is only useful when used with <code>:log_filename</code>.)</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:log_roll_frequency</code></td>
+			<td>This should be either <code>nil</code>, &#8220;daily&#8221;, &#8220;weekly&#8221;, or &#8220;monthly&#8221;, and specifies how frequently the log should be rolled. This option cannot be used with <code>:log_roll_age</code>.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:log_roll_size</code></td>
+			<td>This specifies the maximum size of a log file. Once the log file gets larger than this value, the log will be rolled. (This option is only useful when used with <code>:log_filename</code>.)</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:log_default_date_format</code></td>
+			<td>This is the default date format string to use for the loggers that are created. It may be any string that is understood by <code>Time#strftime</code>. If <code>nil</code> (the default), then the default Logger date format string will be used.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:log_default_message_format</code></td>
+			<td>This is the default message format string to use for the loggers that are created. It is a printf-styled string with special format specifiers&#8212;see the <span class="caps">API</span> documentation for <code>Copland::Logger#message_format=</code> for the available specifiers.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:log_default_level</code></td>
+			<td>This is the default level for each logger. Messages that are logged below this level (also &#8220;priority&#8221; or &#8220;severity&#8221;) will not be logged. By default, all messages are logged.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:log_levels</code></td>
+			<td>This is a hash. Each key should be a string containing a regular expression. For every logger whose name matches one of these patterns, the corresponding value will be used to define specific values for that logger. The value for each key must either be a string (in which case it is the name of the severity level to use), or a hash (containing any of the keys &#8220;level&#8221;, &#8220;date-format&#8221;, or &#8220;message-format&#8221;).</td>
+		</tr>
+	</table>
+
+	<h3>Configuration via <span class="caps">YAML</span></h3>
+
+	<p>The third option (and the most flexible) is to use a <span class="caps">YAML</span> configuration file to define the parameters of the log factory and its loggers. By default, this file is called &#8220;logger.yml&#8221;, but you can specify a different logger configuration file via the <code>:log_config_file</code> option to <code>Copland::Registry.build</code>. By default, the configuration file must reside in current working directory, but you can specify an explicit path in the string you give to <code>:log_config_file</code>.</p>
+
+	<p>The file has options that correspond to the configuration parameters described above:</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>
+<pre>
+  ---
+  filename: log/filename.log
+  roll-age: 5
+  default-date-format: %Y%m%d%H%M%S
+  default-message-format: %p %d %t %C: %m (%l)
+  default-level: DEBUG
+  levels:
+    copland.*: WARN
+    project.*:
+      level: INFO
+      date-format: %Y%m%d::%H%M%S
+      message-format: %p %d: %m
+</pre>
    </div>