copland 0.8.0

data/doc/manual/manual.yml

@@ -0,0 +1,2643 @@
+--- !jamisbuck.org,2004/^manual
+
+# This content is made available under the Attribution-ShareAlike 2.0
+# license from the Create Commons:
+#
+#   http://creativecommons.org/licenses/by-sa/2.0/
+
+meta: !^meta
+  copyright: 2004
+  author: Jamis Buck
+  email: jgb3@email.byu.edu
+
+product: !^product
+  name: Copland
+  tagline: compose yourself...
+  version: !!version ../../lib/copland/version/Copland::Version::STRING
+  logo: copland.png
+  web: http://copland.rubyforge.org
+  project: http://rubyforge.org/projects/copland
+
+recent_updates:
+- described the "initializer block" feature of Registry#service.
+
+chapters:
+
+- Introduction:
+  - What is Copland?: >
+      Copland is an _Inversion of Control_ (IoC) container, written in
+      "Ruby":http://www.ruby-lang.org, for use in Ruby programs.
+      Depending on whether or not the term "IoC" means anything at all to you, 
+      you can read either the next section ("Copland _sans_ Buzzwords"), or the
+      one after it ("Copland _avec_ Buzzwords").
+
+      
+      h3. Copland _sans_ Buzzwords
+
+
+      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's constructor.
+      Nowhere in your code do you specify the instantiation of another application
+      component.
+
+
+      However, those dependencies and relationships between objects _still exist_; you'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 _compose_ them into something greater.
+
+
+      Enter Copland.
+
+
+      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.
+      
+
+      Copland is named after the American composer
+      "Aaron Copland":http://www.lucidcafe.com/library/95nov/copland.html
+      for a reason. You may or may not have any musical talent, but Copland will give you
+      the ability to compose great "symphonies of software" by allowing you to work easily
+      at both extremes of software architecture:
+      
+      
+      # 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.
+
+      # It helps you to focus on the relationships between classes by allowing you to
+      specify those relationships and dependencies as run-time configuration options.
+
+
+      h3. Copland _avec_ Buzzwords
+
+
+      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've used. In the second case, there's probably not much I can say to
+      change your opinion, so I won't try.
+
+
+      I'll save all the meaty discussions for the chapter on Copland's design, but here's
+      the rundown:
+
+
+      * Copland is based heavily on the "HiveMind":http://jakarta.apache.org/hivemind
+      IoC container for Java. If you've ever used that one, much of Copland will probably feel very
+      familiar to you.
+
+      * Copland allows you to define _service points_, _configuration points_, contribute to
+      _configuration points_, add _interceptors_ to services, add _listeners_ to services, define
+      _multicast_ services, and even make your services web-enabled by using the built-in
+      SOAP or dRuby interfaces.
+
+      * Copland uses "YAML":http://www.yaml.org for its configuration files, instead of XML. If
+      you've never used YAML, you'll find it surprisingly easy to pick up.
+
+
+      h3. The Buzzwords Themselves
+
+
+      As "Martin Fowler":http://www.martinfowler.com
+      "points out":http://martinfowler.com/articles/injection.html, the term "Inversion of Control"
+      is a poorly-chosen one. Still, it is the one that most people know the concept by, so I'll
+      use it throughout this document.
+
+
+      For more info about IoC, you might try reading the following articles:
+
+
+      * "Inversion of Control Containers and the Dependency Injection pattern":http://martinfowler.com/articles/injection.html (Martin Fowler)
+
+      * "Inversion of Control":http://docs.codehaus.org/display/PICO/Inversion+of+Control
+      (from the PicoContainer site, another Java-based IoC container)
+
+      * "Inversion of Control":http://jakarta.apache.org/hivemind/ioc.html
+      (HiveMind's take on the subject)
+
+  - Features: >
+      Currently, Copland features the following buzzwords:
+
+
+      * Type 2 IoC (_setter injection_)
+
+      * Type 3 IoC (_constructor injection_)
+
+      * YAML-based descriptor configuration
+
+      * Object-, Class-, and Singleton-backed services
+
+      * Service factories, with extendable rule-processing engine for defining new factories.
+
+      * Interceptors (for adding basic AOP-like "pre" and "post" hooks to every method of a service)
+
+      * Multicast services, which do nothing themselves except delegate recieved messages to a set of
+      other interested services.
+
+      * Event/Listener infrastructure, for notifying services at various points during another
+      service's lifecycle.
+
+      * dRuby and SOAP support, in the form of two core services that applications may use to export
+      their services to remote clients.
+
+  - Getting Copland: >
+
+      h3. Using "RubyGems":http://rubygems.rubyforge.org
+
+
+      Installing via the "RubyGems":http://rubygems.rubyforge.org system is trivial--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:
+
+
+      <pre>
+        gem install copland
+      </pre>
+
+
+      Alternatively, you can download the gem file itself (if, for instance, the RubyGems gem
+      repository is down, or hasn't been updated with the latest version of Copland).  Just go to
+      "Copland's RubyForge project page":http://rubyforge.org/projects/copland and download the
+      gem for the latest version.  Then, from the command-line, type:
+
+
+      <pre>
+        gem install path/to/the/file/you/downloaded.gem --local
+      </pre>
+
+
+      h3. Manual Installation
+
+
+      If, for whatever reason, RubyGems is not an option for you, you can go to
+      "Copland's RubyForge project page":http://rubyforge.org/projects/copland and download the
+      @tar.gz@ file for the latest version of Copland. Then:
+
+
+      # Unpack the archive. It will extract all files to a new directory under the current
+      directory.
+
+      # @cd@ to the new directory.
+
+      # Make sure you are logged in as a user with permissions to install Ruby libraries. If
+      you are, just type:
+
+
+      <pre>
+        ruby setup.rb config
+        ruby setup.rb setup
+        ruby setup.rb install
+      </pre>
+
+  - License Information: >
+      Copland is currently distrubuted under
+      "the BSD license":http://www.opensource.org/licenses/bsd-license.php. Versions
+      of Copland prior to 0.6 were released under
+      "the same license as Ruby":http://www.ruby-lang.org/en/LICENSE.txt.
+
+
+      This manual (both in YAML and HTML formats), as well as the minimal Ruby scripts used to
+      generate it, are distributed under the "Creative Commons":http://creativecommons.org
+      "Attribution-ShareAlike":http://creativecommons.org/licenses/by-sa/2.0 license.
+
+  - Support: >
+      Mailing lists, bug trackers, feature requests, and public forums are available (courtesy
+      of "RubyForge":http://rubyforge.org) at Copland's RubyForge project page. Just direct
+      your browser to "http://rubyforge.org/projects/copland":http://rubyforge.org/projects/copland.
+      
+- Justification:
+  - IoC in One Paragraph: >
+      In one paragraph, "Inversion of Control" is a design pattern that describes the practice of
+      delegating some aspect of control to another part of the program (usually called the
+      "container"). For example, you might invert control over instantiating the dependencies of
+      an object, so that instead of the object instantiating its own dependencies, the container
+      instantiates them for it. This particular inversion of control is called the Dependency
+      Injection pattern by some, because the container is "injecting" the dependencies into
+      the system. "Inversion of Control" is a more general pattern than "Dependency Injection",
+      although you'll sometimes hear them used interchangeably.
+
+  - Why IoC?: >
+      The fact is, most IoC containers provide a few more bells and whistles than just
+      dependency injection.  (Other kinds of control that might be inverted (besides dependencies)
+      include logging, configuration, concurrency, localization, and lifecycle management.) Because
+      these containers provide a meta-programming interface to your objects, they can do a lot of
+      fancy stuff behind the scenes, such as adding AOP-like "before" and "after" hooks, or
+      multicasting.  These meta-programming tools make it easier to extend, debug, and unit-test your
+      sub-systems, and with the dependency injection pattern that is at the core of all IoC
+      containers, you can easily wire your sub-systems together in a non-intrusive, easily-scalable
+      manner.
+
+
+      IoC also makes unit testing easier, because every service is _dependency injected_. This
+      means that instead of the object instantiating all of its dependencies manually, it accepts
+      them as either constructor parameters or properties, so when unit testing you can easily
+      assign mock objects to those dependencies. This simplifies the test cases considerably.
+
+
+      To be sure, IoC is not a panacea. It will not solve every problem that has ever plagued you
+      as a software engineer. Nor will it make every task easier. However, for large and complex
+      systems (and the larger and more complex, the better), the features provided by an IoC
+      container can make designing, implementing, and maintaining that system much easier, since
+      a large part of the complexity of such a system is maintaining the dependencies inside the
+      system.
+
+
+      h3. Why Copland?
+
+
+      Ruby (and scripting languages in general) are not widely viewed by most decision makers as
+      acceptible solutions for enterprise-level applications. In perfect honesty, it must be
+      admitted that there is no single programming language that is the perfect solution to every
+      problem.  However, there are niches where scripting languages (and Ruby in particular) are
+      becoming more and more accepted for large-scale systems. Unfortunately, tools are sadly
+      lacking in Ruby for building large, scalable, and maintainable systems.
+
+      
+      As of this writing, there is only one other IoC container for Ruby,
+      "Rico":http://docs.codehaus.org/display/PICO/Rico. Unfortunately, it is still fairly
+      early in its development, and although it is usable for basic dependency injection
+      needs, even the developers admit that "it is primarily a proof of concept at this stage."
+
+
+      Copland is fairly new, too, but is making great strides forward. It has already gone
+      through one significant rewrite and as a result is much more robust and internally
+      consistant than it was before. It already supports at least
+      as much functionality as most other mature IoC systems, and sports some features that I haven't
+      seen anywhere else. At this point, I have to admit that Copland is perhaps not yet ready for the
+      enterprise, but if enough people play with it and
+      "submit suggestions":http://rubyforge.org/tracker/?func=add&group_id=201&atid=846 and
+      "bug reports":http://rubyforge.org/tracker/?func=add&group_id=201&atid=843, it may
+      not be long before it is.
+
+  - A Case Study: >
+      The following case study has been shamelessly borrowed from the one used in the
+      "HiveMind":http://jakarta.apache.org/hivemind documentation. It is a beautiful
+      and compelling example of the power of IoC. I've paraphrased (and rephrased) portions of it, and
+      removed the lengthy Java and XML sample snippets.  The original author of this case study is
+      "Howard Lewis Ship":http://howardlewisship.com, the creator of HiveMind, and the original
+      version of the case study may be viewed in the
+      "HiveMind documentation":http://jakarta.apache.org/hivemind/case1.html.
+
+
+      Consider a hypothetical product called "Panorama." It is a large web application deployed
+      via WEBrick, and consists of several hundred classes, divided into a large number of tools
+      and services.
+
+
+      Even though Panorama is an enterprise application, it is still logically a number of subsystems.
+      Many of these subsystems require some form of startup and shutdown logic. As an example, the
+      Help service caches help data, which is stored in a database, and the Mail service sets up
+      database cleanup jobs to run at specified intervals.  _In toto_, there are over 40 startup tasks,
+      and a few shutdown tasks.
+
+
+      One way to architect this without an IoC container (because it certainly can be done), is to
+      create a controller object that manages all of the startup and shutdown activity. This controller
+      would be invoked at application start-up, it would run the necessary startup tasks in the
+      required order (since order is important, for some of them), and then
+      when the application shuts down the controller invokes all of the necessary shutdown tasks.
+
+
+      This works, of course. However, you've had to hard-code the dependencies between the controller
+      and the various services; the controller must be aware of every service, and anytime you add a
+      new service, you have to edit the controller.  This can be mitigated to a large degree by having
+      each service register itself with the controller, but there you've got the same problem, to a
+      smaller degree: each service now has an explicit dependency on the controller object, and if
+      you ever refactor that controller class into a different location or a different name, that's
+      40+ services you have to modify!
+
+
+      h3. IoC to the Rescue
+
+
+      IoC moves all of those dependencies out of the code and into configuration files, called
+      (in Copland) _package descriptors_. These descriptors contain service definitions, configuration
+      information, and so forth.
+
+      
+      We do more-or-less what we described in the non-IoC solution, above: we create a service
+      called "Startup", and we have services register themselves with that service. However, the
+      registration is done indirectly, via what is called a "configuration point."  Services
+      are added (along with the order in which they want to be started) to that configuration point,
+      and then the Startup service reads from that configuration point to determine who gets started.
+
+
+      Similarly, we define a "Shutdown" service that reads from yet another configuration point.
+      Services that wish to be notified of system shutdown are added to that configuration point,
+      and the Shutdown service takes care of the rest.
+
+      
+      Finally, we have the Startup service add itself as a listener to the registry, so that when
+      the registry is initialized, the Startup service will be notified. Then, we add Shutdown as
+      a listener to the registry as well, so that when the registry is shutdown, the Shutdown
+      service can take any necessary actions.
+
+      
+      h3. Summary
+
+
+      Certainly, you could implement all of this yourself. It's nothing magical or new. However, you'd
+      just be implementing a special case of an IoC container, and if you ever wanted to add logging
+      or security to your "services", you'd find yourself diving back into your code to add the
+      necessary calls at various points.  Before you know it, you'd find that you'd have implemented
+      an IoC container after all.
+
+
+      Copland offers these features "out-of-the-box". Applications can easily take advantage of them.
+      Developers don't need to spend time reinventing the wheel (even though that is often most of the
+      fun of some projects).
+    
+- Getting Started:
+  - Terminology: >
+      In the tutorials and examples that follow, you'll see a lot of (potentially) new terminology.
+      Here is a brief glossary of some of the more prominant terms, to help you get started. Don't
+      feel like you need to read and understand each term before proceeding through this manual;
+      just know that you can refer back to these if you need to.
+
+
+      * *configuration point*: This is either a list or a map (configurable) which packages may
+      contribute to, and which services may read from to initialize themselves. Packages may
+      define multiple configuration points.
+
+      * *contribution*: This is how a package contributes to a _configuration point_. A package may
+      have any number of contributions, to any number of configuration points. Contributions may
+      be made to configuration points both inside and outside of the current package.
+
+      * *dependency injection*: A design pattern in which the dependencies of an object are
+      managed independently of the object, usually by some "container" framework. See "inversion
+      of control".
+
+      * *event producer*: A service that other services may listen to in order to obtain
+      notifications of various service-specific events.
+
+      * *interceptor*: An interceptor is a special object that is attached to a service. A _chain_
+      of interceptors may wrap the methods of a service and act as filters for any invocations
+      of those methods. This is the means by which AOP-like "pre" and "post" hooks are
+      implemented in Copland.
+      
+      * *inversion of control*: A general design pattern in which various types of control are
+      delegated ("inverted") to some enclosing framework, called a "container", "Dependency
+      injection" is one form of control inversion, though the two terms are sometimes used
+      interchangeably.
+
+      * *listener*: A service that has been registered with another service point in order to
+      receive events produced by the latter service.
+
+      * *package*: The unit of organization in Copland. All _service points_, _configuration points_,
+      and _contributions_ are grouped into _packages_. Each _package_ is defined in its own
+      _package descriptor_.
+
+      * *package descriptor*: The file that contains the definition of single package. This always called
+      @package.yml@ and contains YAML.
+
+      * *multicast service*: A special kind of service that, by itself does nothing, but which other
+      services may register themselves with. Then, when a method on the multicast service is invoked,
+      the corresponding methods of all registered services will be invoked.
+
+      * *registry*: This is the primary interface into Copland, used by clients. It is the broker
+      that returns _services_ requested by clients.
+
+      * *service*: This is the basic unit of activity in Copland. The _service model_ determines how
+      the service is instantiated, such as whether it is a singleton or not. Some services are actually
+      _service factories_ which may in turn be used to help create more complex services. Another
+      special type of service is the _interceptor factory_, which is used to create interceptor
+      instances. An application's components will typically be implemented as services.
+
+      * *service factory*: A service factory is a special kind of service, which may be used to
+      bootstrap the creation of more complex services. Copland comes with several predefined service
+      factories, most notably the "BuilderFactory" (which may be used to create the vast majority of
+      the services you will need).
+
+      * *service model*: A service model defines how and when a service is instantiated. There are
+      six predefined service models, allowing for simple instantiation (one instance per request,
+      created at the time of the request), singleton instantiation (only one instance of the service
+      is ever created, and it will be returned every time the service is requested), deferred
+      instantiation (the service will be created the first time a method is invoked on it), and even
+      combinations of these. The default model is "singleton deferred".
+
+      * *service point*: A definition of a service. A service point is to a service as a class is to
+      an object. The service point contains the configuration of interceptors, event producers, service
+      model, service factory, and so forth that will be used to construct its corresponding service.
+
+  - Quickstart: >
+      This "Quickstart" is designed to show you the "look" of a simple Copland application. It is
+      not intended to teach you how to use Copland, nor to be an example of application design in
+      Copland. Very little time will be spent on explanation. If you wish to actually learn how to
+      use Copland, refer instead to the Tutorials section, and the Examples section.
+
+
+      h3. Service Implementation
+
+
+      A service is typically backed by a simple, ordinary Ruby object, instantiated from a class.
+      You don't have to do anything special to your definition of the class (unless you want it
+      to interact with other services--but that's beyond the scope of this "quickstart").
+
+
+      <pre>
+        class ASimpleService
+          def do_something
+            ...
+          end
+
+          def do_something_complicated( a, b, opts={}, &block )
+            ...
+          end
+        end
+      </pre>
+
+
+      For the rest of this example, we'll assume the above implementation is contained in a file
+      called @simple-service.rb@.
+
+
+      h3. Service Definition
+
+
+      The services are always defined in a package descriptor file. This file is always named
+      @package.yml@, which means you can only have one per directory. It is a YAML-formatted
+      description of a package, which will include all of the service points (service definitions)
+      for that package.
+
+
+      <pre>
+        ---
+        id: quickstart
+
+        service-points:
+
+          SimpleService:
+            implementor: simple-service/ASimpleService
+      </pre>
+
+
+      h3. Registry Initialization
+
+
+      Creating a registry is simple: just invoke @build@ on the Registry class.
+
+
+      <pre>
+        require 'copland'
+
+        registry = Copland::Registry.build
+      </pre>
+
+
+      The @build@ method is a convenience method. It takes care of searching
+      subdirectories for package descriptors and adding them to the new registry.
+
+      
+      h3. Getting Services
+
+
+      Services are queried through the registry. The name of a service is the name of it's
+      package (the 'id' in the package descriptor), followed by a dot '.', followed by the
+      id of the service.
+
+
+      Once you have a reference to the service, you can invoke its methods just as if it were
+      a plain-old Ruby object.
+
+
+      <pre>
+        service = registry.service( "quickstart.SimpleService" )
+        service.do_something
+        service.do_something_complex( 1, 2, :name=>"Jim" ) { |a| puts "#{a}: here" }
+      </pre>
+
+
+      h3. Service Initialization
+
+
+      Sometimes (especially for "prototype" services--see the prototype service model for
+      more info) you want to be able to pass some kind of initialization data to the new
+      service the first time it is initialized. You _could_ do this with a method that you
+      explicitly call after obtaining a reference to the service--but then the service needs
+      to keep track of whether the method has already been invoked or not, to prevent the
+      initialization from occurring more than once per service instance.
+
+
+      To make this simpler, Copland 0.8 introduced the concept of an _initialization block_.
+      When you call @Registry#service@, you can attach a block to it, and that block will be
+      passed to @instance_eval@ on the new service every time that service is instantiated.
+
+
+      Something like this:
+
+
+      <pre>
+        service = registry.service( "quickstart.SimpleService" ) do
+          ...
+          # put your initialization code here, to be executed every
+          # time this service is instantiated.
+          ...
+        end
+      </pre>
+
+
+      If the service was instantiated previously (i.e., it is a singleton service and
+      was requested earlier), then the initialization block will be ignored.
+
+- Copland's Design:
+  - >
+    Here you'll read about various issues regarding Copland's design. These will probably not be
+    interesting to anyone except those who want to dig into Copland's internals.
+
+  - HiveMind: >
+      Copland borrows much of its design from the "HiveMind":http://jakarta.apache.org/hivemind
+      IoC container for Java. However, Copland was written without significant experience with HiveMind's
+      internals, so although they may look similar on the outside, their implementations will differ
+      significantly.
+
+
+      h3. Similarities
+
+
+      Copland uses HiveMind's concepts of "modules" (but calls them "packages"), "service points",
+      "configuration points", and "contributions". Also, a "service models" are borrowed from
+      HiveMmind, although Copland implements them in a more flexible (and extensible) manner.
+
+
+      The idea of a _service factory_ was also borrowed from Copland.
+      HiveMind supports digester-like "rules" for processing descriptor files, but because of
+      Ruby's highly dynamic nature, such complexity was not necessary.
+
+
+      Interceptors, and the way they get created (via special "interceptor factories") are identical
+      to HiveMind's interface.
+
+
+      h3. Differences
+
+
+      HiveMind uses XML for it's module descriptors. Copland uses YAML.
+
+
+      HiveMind's configuration points revolve around XML--you define a configuration point and
+      a schema to go with it, and all contributions to that configuration point must match that
+      schema. Copland's approach is simpler: simply declare whether a configuration point is a
+      list or a map, and then all contributions must be either in the form of list elements to
+      append to the configuration point, or map elements to merge into it.
+
+
+      Copland names the service models differently:
+
+
+      | *HiveMind* | *Copland* |
+
+      |=. --- |<. prototype |
+
+      |=. --- |<. prototype-deferred |
+
+      | primitive | singleton |
+
+      | singleton | singleton-deferred |
+
+      | threaded | threaded |
+
+      | pooled |=. --- |
+
+
+      Events and listeners exist in HiveMind, too, but because of Ruby's dynamic nature they
+      can be implemented much more simply in Copland. Therefore, the way they are declared and
+      used is different in Copland.
+
+
+      Multicast services do not exist in HiveMind, nor do services that are backed by anything
+      other than objects. Copland allows services to be backed by classes and singletons, as well
+      as objects.
+
+  - Registry Initialization: >
+      The initialization process for the registry consists of two phases. The first phase is where the
+      package descriptors are loaded and parsed. Once all of the packages have been loaded the
+      the second phase is started, which causes all of the packages to process those parts of
+      themselves that refer to other packages. This includes contributions to configuration points
+      and processing any referenced parameter schema definitions.
+
+
+      One the initialization has been completed, the registry (which is itself exported as a service)
+      loads the copland.Startup service and instructs it to start any services that have registered
+      themselves with it (via its configuration point).
+
+  - Service Instantiation: >
+      The way a service is instantiated depends on two things: it's _service model_, and its
+      _instantiator_ (or _implementor_).
+
+
+      The _instantiator_ defines _how_ the service is instantiated. It may
+      either be a string (in which case the service is created simply by calling 'new'
+      on the class described by that string), or a map, in which case the creation of the
+      class is delegated to a service factory.  These two approaches are defined inside Copland
+      as "instantiation factories", with the first being @Copland::Instantiator::Simple@,
+      and the second being @Copland::Instantiator::Complex@.
+
+
+      The _service models_ define _when_ the service is instantiated. For example, the "singleton"
+      model says that a service is only instantiated the first time it is requested, with
+      subsequent requests returning the cached instance.  The "singleton-deferred" model
+      indicates that a service should only be instantiated the first time any of its methods
+      are invoked (this level of granularity is achieved via a proxy object that defers instantiation
+      of its wrapped service).
+
+
+      Thus, when a user requests a service, the registry calls the @#instance@ method of the
+      corresponding service point.  This calls the @#instance@ method for the service point's model,
+      and the service model may then either call the service point's @#instantiate@ method (to actually
+      instantiate the service point) or return a cached instance.
+
+
+      The service point's @#instantiate@ method will call the @#instantiate@ method for the instantiation
+      factory for this service point. The @Simple@ factory simply calls @#new@ on the service point's
+      backing class, but the @Complex@ factory will basically "execute" the parameter scheme for the
+      service factory that was specified, and then invoke the @#create_instance@ method of the service
+      factory.  Either way, the backing object for the service is returned.
+
+
+      Then, any interceptors that were specified are added to the new service, the new service is
+      added as a listener to any requested event producers, and the new service is returned.
+
+  - Interceptor Chains: >
+      Interceptor chains are implemented as chains of proxy objects, each of which wraps an
+      interceptor instance. Each method of the service that is being intercepted is then
+      renamed and replaced with a new method, which just executes the @#process_next@ method on
+      the first element in the chain. When the last element of the chain invokes the @#process_next@
+      element on what it believes to be the next link, the renamed method of the service is
+      invoked.
+
+      
+      This makes it look to each interceptor as if they are a filter for the message invocation,
+      which indeed they are. Each interceptor may invoke the @#process_next@ method of the next
+      link in the chain, if they desire, or not, if they desire.
+
+- Packages:
+  - >
+    Packages are the unit of organization in Copland. All service and configuration points are
+    grouped in packages.
+
+  - Descriptor Syntax: >
+      Each package is described in a single file, named "package.yml". (You can actually change
+      what the descriptor file name ought to be--the default, though, is "package.yml"). It will
+      typically contain all of the services defined in the same directory. In keeping with standard
+      YAML syntax, this file should begin with a single line consisting solely of three dashes: @---@.
+
+
+      The file may contain the following attributes:
+
+      
+      table(list).
+      
+      |^. @id@|This is the name of the package. It must be a string, and it must be
+      unique. If the registry encounters a package named identically to some other package it has
+      already parsed, it will raise an exception.|
+
+      |^. @require@|This is a list of other (non-core) packages that this package depends on.
+      For example, to take advantage of any of the services in the "copland.lib" namespace, you
+      would need to add "copland/lib" to the require list for the package that needs those
+      services.|
+
+      |^. @description@|This is an (optional) description of the current package. It is useful for
+      documentation purposes, but is not used at all by Copland itself.|
+
+      |^. @configuration-points@|This must contain a hash of values, each key of which names and
+      references the definition of a _configuration point_ (q.v.).|
+
+      |^. @contributions@|This must contain a hash of values, each key of names a contribution to
+      some configuration point. (See the chapter on contributions for more information.)|
+
+      |^. @service-points@|This must contain a hash of values, each key of which names and references
+      the definition of a _service point_ (q.v.).|
+
+
+      Of the attributes descibed above, only the @id@ attribute is required, though it makes little
+      sense to define a package that does not include at least one configuration point, contribution,
+      or service point.
+
+
+      Also, if your package references any non-core packages (like "copland.lib" or "copland.remote"),
+      you will need to add the requisite libraries to your package's @require@ clause.
+
+  - Tips: >
+      Name your packages consistently. Here is a recommended naming convention:
+
+
+      * Use dashes instead of underscores in your package names.
+
+      * Make package names all lowercase.
+
+      * Name your primary package after your application.
+
+      * If your application uses more than one package (and large applications very well may),
+      prefix each package name with the name of your application, followed by a dot. In other
+      words, if your application was named "Astroscopus", and you had a subpackage named
+      "notewise", you would name your primary package "astroscopus", and the subpackage
+      "astroscopus.notewise". This gives your packages a hierarchical feel, though there is
+      nothing saying they need to be laid out in a hierarchical directory structure.
+
+      * If you are distributing a package that you created for others to use, name
+      the package with your name or company (or website) as the primary package name, and your
+      library as the secondary name.  For instance, if your company was "Interrelated Autorotation, Inc.",
+      and you created a library called "papillomatosis", you might name your package
+      "interrelated-autorotation.papillomatosis".
+
+
+      Try to group the service points and configuration points in your packages by common functionality.
+      Don't be afraid to create new packages where necessary to separate functional groups. Although having
+      many packages may make your application's start-up time a little slower (and it will only be a little),
+      it is worth the benefits to maintainance it will add.
+
+- Service Points:
+  - >
+    A _service point_ is a definition of a service. It describes how and when the service should be
+    instantiated, what parameters should be passed to it when it is created and what properties assigned,
+    what other services it should listen to, and so forth. You could say that a service point is to a
+    service, as a class is to an object. That is to say, a service point is simply a template for how
+    a service should be created.
+
+  - Descriptor Syntax: >
+      Every service point must be defined as part of the "service-points" section of a package
+      descriptor. The id (or name) of the service point will be the key used in that section to
+      reference it, and it may contain any character you wish except for a ".". Also, if you use
+      any character that YAML treats specially (like commas, or colons), you'll need to put the
+      service name in quotes.
+
+
+      Whenever the name of a class is required (for a service, for instance), it must be in a
+      particular format. The name of the class must be prefixed with the path that must be
+      required (ie, the file that contains the class), followed by a forward slash ("/"),
+      followed by the complete name of the class (including any modules that it is defined
+      inside of).  For example:
+
+
+      <pre>
+        some/special/service/MyServices::MyService
+      </pre>
+
+
+      The above example indicates a class named @MyService@, defined inside of a module
+      called @MyServices@, and which is contained in a file called @some/special/service.rb@.
+
+
+      The allowed attributes of a service point are:
+
+
+      table(list).
+
+      |^. @description@|this (optional) attribute is useful for documentation purposes, but has no
+      use at all inside Copland.|
+
+      |^. @model@|This describes how (and when) the service will actually be instantiated. It must
+      be either @simple@, @simple-deferred@, @singleton@, @singleton-deferred@, @threaded@, or @pooled@
+      (or, if you've defined a custom service model, the name of that custom service model). If this
+      attribute is not specified, it defaults to @singleton-deferred@. (See the chapter on "Service
+      Models" for more information.)|
+      
+      |^. @implementor@| This describes how the service should be _implemented_. If the value of
+      this attribute is a string, then it must be the name of the class to instantiate. (If the
+      class includes the Singleton mixin, then the singleton instance will be returned; otherwise
+      a new instance of the class will be created.) If this value is a map, then it may contain
+      at the key @factory@. This must identify a _factory service_ which will be used to
+      create the new service. (If omitted, it defaults to @copland.BuilderFactory@.) In addition
+      to the @factory@ attribute, the hash should contain any other attributes required by the
+      service factory that was specified. See the documentation for the corresponding service factory
+      for a description of which attributes are available.|
+
+      |^. @interceptors@|This must be an array of interceptor definitions, each of which is a hash.
+      The only required key in each hash is @service@, which names the interceptor factory service
+      to use when instantiating the corresponding interceptor. The other allowed attributes are @before@
+      and @after@, which may be used to define the order in which the interceptors are applied.
+      Besides those two attributes, some interceptors may allow additional attributes to be specified
+      in order to configure them. See the documentation for those interceptors for more information.|
+
+      |^. @schema@|This must be either a string or a hash. If it is a string, then it references
+      another schema (either in this package or a different one). Otherwise, it's format is described
+      in more detail in the chapter "Schemas". This is only needed by services that
+      define service or interceptor factories.|
+
+      |^. @listen-to@|This must be an array of service point names. If the referrenced service points are
+      not defined in the same package as the current service point, their full names (including package)
+      must be given, otherwise the package name may be omitted. Every time the current service point is
+      instantiated, the new instance will be added as a listener to each of the service points listed
+      here, to be notified when some service-specific event is triggered. See the chapter on
+      "Listeners and Event Producers" for more information.|
+
+
+      Of these attributes, only @implementor@ is required.
+
+- Service Models:
+  - >
+    Service models are used to specify when a service point should be instantiated.  There are
+    five pre-defined service models, and you can easily define more yourself should you need them.
+
+
+    The service model for a service point is specified using the @model@ attribute in the service
+    point definition. This attribute is optional, defaulting to @singleton-deferred@, but if given it
+    must refer to either one of the five standard service models, or to a custom service model you have
+    defined.
+
+
+  - Standard Models: >
+      The five standard service models are:
+
+
+      table(list).
+
+      |^. @prototype@ | A service point using this model will be reinstantiated every time it is requested.
+      This may be useful, for instance, when the requested service is stateful, and you do not want instances
+      of the service to be reused.|
+
+      |^. @prototype-deferred@ | This is the same as the @prototype@ service model, except that the
+      service will not be instantiated until the first time any of its methods are invoked. Thus, if
+      you _might_ need the service, but there are some paths through your program that won't use it,
+      you can use this model so that the overhead of initializing the service only occurs when you
+      actually invoke a method on it.|
+
+      |^. @singleton@ | Only one instance of the service is ever created. Any subsequent request for the
+      service will return the instance that was created the first time. This is the most common scenario
+      for most services, since in general a service is either stateless, or its state is effectively
+      global throughout an application.|
+
+      |^. @singleton-deferred@ | This is identical to the @singleton@ model, above, but also has the
+      deferring functionality of the @prototype-deferred@ model.|
+
+      |^. @threaded@ | This model results in every thread obtaining its own instance of a service. It is
+      otherwise identical to @singleton-deferred@.|
+
+  - Deferred Instantiation: >
+      Using one of the "deferred" service models (@prototype-deferred@, @singleton-deferred@, or @threaded@)
+      can be very useful, but there are side-effects that you ought to be aware of. Otherwise,
+      you may spend a lot of time debugging some difficult-to-track-down problems.
+
+
+      In particular, it is important to keep in mind that the service is not actually instantiated until
+      a method is invoked on it. This means that if the service's initialization routine raises an error,
+      the exception will not occur where the reference to the service was obtained, but will occur where
+      the method call was made. The service will also not have been properly instantiated, so if you
+      try to inoke any of its methods again, you'll get @nil@ back every time.
+
+
+      For example, consider the following scenario.
+
+
+      Suppose you are writing a web-application framework, using Copland to modularize the various
+      components. One of the services you create is a "page manager", which will broker all requests
+      for page objects. When an application needs a page, it queries the page manager, which will 
+      look up the page and return it.
+
+
+      You make the page manager service @singleton-deferred@.
+
+
+      Now, inside the controller for your architecture, you grab a reference to the page manager.
+      (Note, however, that the object you are given is _not_ the page manager--instead, it is a proxy
+      object that will instantiate the page manager the first time a method is invoked on it.) Some time
+      later you invoke @#get_page@ on the page manager, which you expect to go grab a page object and
+      return it.
+
+
+      _However_. What actually happens is this: the proxy object intercepts the method call and tries
+      to instantiate the page manager service, since it hasn't been instantiated yet. During the
+      page manager initialization, however, something goes wrong. Perhaps one of the page classes
+      doesn't exist, or there is a syntax error in one of the files that the page manager needs to
+      require. Whatever it is, the page manager cannot be initialized and an exception is thrown.
+
+
+      The controller code catches the exception.
+
+
+      _Problem_. Inside the rescue clause for the exception, _the controller queries the page manager
+      for the error page_, so that it can display a coherent error to the client. However, since there
+      was an error instantiating the page manager, future queries to the proxy object always return
+      @nil@. This may result in an "undefined method `x' for nil:NilClass" error down the road.
+
+
+      To avoid problems like this, you can do one of two things. One, you can use the @singleton@ model,
+      instead of @singleton-deferred@. This way, Copland will never deliver you a reference to a proxy.
+      The other solution is to create a method in your class that always returns non-@nil@. Then, if
+      it ever _does_ return @nil@, you can be pretty sure that the service was not instantiated correctly.
+      This, unfortunately, requires your code to know that the service was deferred.
+
+  - Custom Service Models: >
+      Creating your own service models is very straight-forward. In general, all you need to do is
+      create a class. The class should extend the @Copland::Instantiator::Abstract@ class, and must
+      override the @instantiate@ method. The @instantiate@ method should accept a no parameters.
+      The method should then return an object that represents the instantiated service.
+
+
+      After creating the class, you need to register it with the @Copland::ClassFactory@
+      class by calling it's @register@ method, passing the name to want for this new model, and
+      a reference to the class that implements it.
+
+
+      To return a deferred version of the service, return a new instance of @Copland::Instantiator::Proxy@.
+      The proxy's constructor accepts a single parameter: the service point to instantiate.
+
+
+      To create a singleton service, the @instantiate@ method should cache the new service, returning
+      it (if it exists) instead of instantiating a new service.
+
+
+      Lastly, be aware that you may need to do some synchronization via mutexes to make your new
+      service model thread-safe. Multiple threads could call it concurrently, which may cause
+      problems if your model stores any state (as is the case with models that enforce a singleton
+      model of service instantiation).
+
+
+      Here's a brief example of a custom service model, pulled off the top of my head:
+
+
+      <pre>
+        class FiveMinuteServiceModel < Copland::Instantiator::Abstract
+          CachedService = Struct.new( :service, :time )
+
+          def initialize( point, definition )
+            super
+            @mutex = Mutex.new
+            @service_cache = Hash.new
+          end
+
+          def instantiate
+            @mutex.synchronize do
+              svc = @service_cache[ point ]
+
+              if svc.nil? || Time.now - svc.time > 300
+                svc = CachedService.new( point.instantiate, Time.now )
+                @service_cache[ point ] = svc
+              end
+
+              return svc.service
+            end
+          end
+
+          register_as "custom.five-minutes"
+        end
+      </pre>
+
+
+      This (contrived) example will result in a singleton-style model (non-deferred),
+      which will instantiate the requested service point if it has been more than five
+      minutes (300 seconds) since the point was last instantiated. It can be referenced
+      in a service point definition under the @model@ attribute, as "custom.five-minutes".
+
+- Configuration Points:
+  - >
+    A _configuration point_ is either a list or map that other packages may contribute
+    values to. You can then have Copland automatically wire that configuration point into
+    a service.
+
+
+    Why would you want to do this? Various reasons. One is so that you can allow other
+    packages to configure the behavior of a particular service. The @copland.remote.DRbServer@
+    service, for example, does this, to allow applications to configure the host and port
+    that should be listened to, and whether or not the service should be automatically started.
+
+
+    Values are added to a configuration point via the "contributions" section of a package
+    descriptor.
+
+  - Descriptor Syntax: >
+      Every configuration point must be defined as part of the "configuration-points" section
+      of a package descriptor. The id (or name) of the configuration point will be the key used
+      in that section to reference it, and it may contain any character you wish except for a ".".
+      Also, if you use any character that YAML treats specially (like commas, or colons), you'll
+      need to put the configuration name in quotes.
+
+
+      The allowed attributes of a configuration point are:
+
+
+      table(list).
+
+      |^. @description@ | This is an (optional) description of what the configuration
+      point describes. Where a schema (see below) is insufficient, the description may also
+      be used for describing what kinds of values the configuration point expects.|
+
+      |^. @type@ | This is the type of the configuration point. By default, only @list@
+      and @map@ are supported, but you can add your own configuration point types.|
+
+      |^. @schema@|This must be either a string or a hash. If it is a string, then it references
+      another schema (either in this package or a different one). Otherwise, it's format is described
+      in more detail in the chapter "Schemas". This is used to restrict the values
+      that can be contributed to the configuration point. If the configuration point is of type
+      @list@, then the schema applies to each element of the configuration point. Otherwise, the
+      schema describes the format of the map.|
+
+
+      Of these attributes, only @type@ is required.
+
+  - DefaultSymbolSource: >
+      One of the core pre-defined configuration points is the map @copland.DefaultSymbolSource@.
+      Although you will rarely access this configuration point directly, it is integrated
+      tightly with Copland. Any value you add to it becomes available as a _substitution
+      symbol_.
+
+
+      Substitution symbols will look familiar to those of you coming from a Java background;
+      utilities like "ant":http://ant.apache.org and "maven":http://maven.apache.org make
+      heavy use of them.  What they are, is this: any time Copland encounters a value that
+      contains a certain pattern, it replaces that pattern with the value of the same name
+      from the DefaultSymbolSource.  The pattern is a dollar sign, followed by curly braces
+      that contain the name of the symbol.
+
+
+      For example, suppose you want to allow the application to configure which class gets
+      used when a particular service point is instantiated. You can do this by pulling the
+      name of the class from the DefaultSymbolSource as a substitution symbol:
+
+
+      <pre>
+        SomeServicePoint:
+          implementor: ${the.class.to.use}
+      </pre>
+
+
+      Then, the application would contribute a value named @the.class.to.use@ to 
+      @copland.DefaultSymbolSource@, and when @SomeServicePoint@ is instantiated, it would
+      use the value thus provided.
+
+- Contributions:
+  - >
+    _Contributions_ are the means by which packages may add values to configuration points.
+    In general, the value of a contribution must match both the _type_ of the configuration
+    point, and the requirements of any _schema_ that the configuration point may possess.
+
+
+    Adding contributions is simple. All contributions must go in the _contributions_ section
+    of the package descriptor. Then, specify a map key with the name of the configuration
+    point you want to contribute to, and then specify (as the value of the key) the value(s)
+    you want to contribute.
+
+
+    For example, to contribute a value to the DefaultSymbolSource configuration point:
+
+
+    <pre>
+      contributions:
+
+        copland.DefaultSymbolSource:
+          user.name: fritz
+    </pre>
+
+
+    That little snippet just added a value called @user.name@ to the @copland.DefaultSymbolSource@
+    configuration point!
+
+- Service Factories:
+  - >
+    Sometimes it requires a little more effort (or a lot more effort) to instantiate and
+    initialize a service than simply calling @#new@ on it's associated class. In such cases,
+    you need to rely on a _service factory_ to instantiate the service.
+
+
+    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: @#create_instance@. This method should accept two parameters, the
+    _service point_ to instantiate, and the _parameters_ associated with this instantiation.
+    (The @parameters@ parameter will always be a hash.)
+
+
+    Here is an example that implements a trivial service factory:
+
+
+    <pre>
+      class ExampleServiceFactory
+
+        def create_instance( point, parms )
+          return { :point => point,
+                   :parms => parms }
+        end
+
+      end
+    </pre>
+
+
+    This service would be introduced into Copland via the following package
+    descriptor:
+
+
+    <pre>
+      ---
+      id: example
+
+      service-points:
+
+        ExampleServiceFactory:
+          implementor: some/file/ExampleServiceFactory
+    </pre>
+
+
+    And it would be employed like this:
+
+
+    <pre>
+      ---
+      id: demo
+
+      service-points:
+
+        ExampleService:
+          implementor:
+            factory: example.ExampleServiceFactory
+    </pre>
+
+
+    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 @ExampleService@
+    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.
+
+  - Schemas: >
+      As mentioned in the chapter on service points, a service point may be associated
+      with a _schema_. 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.
+
+  - How do they work?: >
+      When you specify a factory service as the implementor of another service, Copland
+      automatically marks that service point as needing a _complex instantiator_. 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's @#create_instance@ method is called. The result of that call
+      is then treated as the new service.
+
+
+      Contrast this with the _simple instantiator_. When the simple instantiator is used,
+      all it does (more or less) is invoke @#new@ on the named class and return the result.
+      The existence of factory services allows for much more complex (and powerful)
+      behavior.
+
+  - BuilderFactory: >
+      Copland comes with one predefined factory service: @copland.BuilderFactory@. With
+      this factory you can implement most of the more common types of services. (There are
+      always special cases, though--the @copland.lib@, @copland.remote@ and @copland.webrick@
+      libraries all define additional factory services for specialized uses.)
+
+
+      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 "dependency injection" aspect of Copland comes into play.
+
+
+- Schemas:
+  - >
+    "Schemas" 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.
+
+
+  - Basic Format: >
+      In YAML terminology, a schema is simply a map that follows a special format. Consider
+      the following configuration point:
+
+
+      <pre>
+        MyConfigurationPoint:
+          type: map
+          schema:
+            definition:
+              user.name:
+                type: string
+                required: true
+              home.directory:
+                type: string
+              user.groups:
+                type: array
+      </pre>
+
+
+      This configuration point is a map that only allows three keys: @user.name@,
+      @home.directory@, and @user.groups@. Any contribution made to this configuration point
+      _must not_ contain any keys other than these values. And since the @user.name@ key
+      is marked as required, any contribution to this configuration point _must_ contain
+      at least that key.
+
+
+      Note the type definitions as well. The recognized types are:
+
+
+      * @any@
+
+      * @array@
+
+      * @configuration@
+
+      * @integer@
+
+      * @log@
+
+      * @hash@
+
+      * @real@
+
+      * @service@
+
+      * @string@
+
+
+      If the type is left out, it defaults to @any@. If a value is contributed to that
+      key that is not of the required type, a validation error results.
+
+
+      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 @schema@
+      descriptor element.) In that case, the schema applies to the parameters of any
+      service point that uses this service point as its factory service.
+
+  - Subschemas: >-
+      Schemas may be nested, to allow for arbitrarily deep schema "trees". Consider the
+      following example:
+
+
+      <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>
+
+
+      In this case, the @user.address@ element of the schema is itself _another schema_.
+      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 (@line1@, @line2@, @city@,
+      @state@, and @zip@).
+
+
+      If you specify a subschema definintion (via the @definition@ keyword), and the same
+      element is of any type other than @hash@ or @array@, you'll get an error. You cannot
+      used schema's to validate any other type of data. (Arrays are a special case--see
+      the next section.)
+
+  - Arrays: >-
+      When you specify a schema for an array (or for a configuration point of type @list@),
+      the schema will be applied to every element of any array that is contributed. For
+      example, consider this:
+
+
+      <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>
+
+
+      This configuration point is a @list@. Every element that is contributed to it
+      must conform to the given schema. Note, too, that the @actors@ element of the
+      schema expects an array, and that each element of _that_ array must conform to
+      the given subschema.
+
+
+      Given that schema, the following contribution would be valid:
+
+
+      <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>
+
+  - Named vs. Anonymous Schemas: >-
+      The schemas that have been shown so far have been _anonymous_. 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.
+
+
+      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).
+
+
+      To name a schema, just add a @name@ element at the same level as the @definition@
+      element:
+
+
+      <pre>
+        MoviesILike:
+          type: list
+          schema:
+            name: MovieDefinition
+            definition:
+              ...
+      </pre>
+
+
+      Then, you can reuse the schema by putting the schema name after the @schema@ element,
+      instead of a hash:
+
+
+      <pre>
+        MoviesIHate:
+          type: list
+          schema: MovieDefinition
+      </pre>
+
+
+      This second configuration point will reuse the @MovieDefinition@ schema.  Note
+      that you can specify an existing schema (or name a schema) at any level of a
+      schema definition:
+
+
+      <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>
+
+  - Extending Schemas: >-
+      Sometimes it happens that you want to create a schema that is _almost_ like an
+      existing schema, but adds one or two new elements. You can do this in Copland
+      by _extending_ the existing schema:
+
+
+      <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>
+
+
+      In the above instance, the "EmployeeSchema" is exactly like the PersonSchema,
+      except it adds a "department" key.
+      
+  - Limitations: >-
+      The existing schema implementation is sufficient for most purposes, but it has
+      some limitations:
+
+
+      * You cannot specify a format for a non-hash value.
+
+      * You cannot specify whether a subschema that reuses an existing schema is
+      required or not.
+
+      * You cannot enforce the constraint "any one of a set of keys is required." The
+      schema subsystem only understands a single key being required or not.
+
+
+      For most purposes, however, it is sufficient.
+
+- Listeners and Event Producers:
+  - >
+    Sometimes, you may have a service that produces events. In terms of a GUI, you might
+    have a button that emits events liked "clicked", "mouse over", "mouse out", "mouse down",
+    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.
+
+  - Event Producers: >
+      At one end of this functionality is the _event producer_. Using the above example, this
+      would be the button. It is the service that generates and emits the events.
+
+
+      Any service can be an event producer--all it requires is that the service implement an
+      @#add_listener@ 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 @singleton@ and
+      @singleton-deferred@ model.
+
+
+      When an event occurs, the producer should notify those registered listeners by
+      invoking a method on them. The method should be named "on_#{event}" (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.
+
+      
+      Optionally, if a listener does not respond to a specific event, the producer may look for
+      a method called "on_any_event"; 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.
+
+
+      To make it easier to create event producers, you can mixin the Copland::EventProducer module
+      into your existing services. It provides several methods, including @#add_listener@ and
+      @#fire_event@.
+
+
+      <pre>
+        require 'copland/event-producer'
+
+        class MyProducerService
+          include Copland::EventProducer
+
+          def click
+            do_something_about_it
+            fire_event :clicked
+          end
+
+          def mouse_over
+            do_something_else_about_it
+            fire_event :mouse_over
+          end
+        end
+      </pre>
+
+  - Listeners: >
+      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.
+
+
+      As described above, the listener methods are named "on_#{event}", where "event" is the name
+      of the event to listen to. Alternatively, a listener may declare a method called
+      "on_any_event", which will be called for any event that does not have an explicit listener
+      method declared for.
+
+
+      <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
+      </pre>
+
+
+      To register interest in the producer, use the @listen-to@ 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 @listen-to@ elements will be
+      processed and the new service will be added to each of those service points in
+      turn, as a listener:
+
+
+      <pre>
+        service-points:
+
+          Producer:
+            implementor: MyProducerService
+
+          Listener:
+            implementor: MyListenerService
+            listen-to:
+              - Producer
+      </pre>
+
+  - The Registry as an Event Producer: >-
+      Currently, Copland only comes with one event producer built in--the registry itself.
+      Every time you instantiate a registry, it adds itself to itself as the
+      "copland.Registry" service. When the registry is shutdown, it emits a
+      @:registry_shutdown@ event to all of its listeners.
+
+
+      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 "copland.Registry",
+      and implement a listener method called @on_registry_shutdown@ (or @on_any_event@).
+
+tutorials:
+
+- Creating Services:
+    brief: The basics of creating new services in Copland.
+
+    intro: >-
+      A "service" is just an object. A plain, old, vanilla-flavored Ruby
+      object. It's as simple as that. You create a Ruby object, define methods
+      and attributes on it, put it in Copland, and voila! Instant service.
+
+
+      I'm assuming you already know how to create Ruby objects. (If not, you may
+      want to check out a more basic tutorial.) This tutorial will show you how
+      to plug those objects into Copland, and how to access them in your program.
+
+    steps:
+    - >
+      h3. Implement the Service
+
+
+      For this tutorial, we'll create a service that adds two numbers and returns
+      the result. Pretty basic, but easy to understand.
+
+
+      So, first things first: let's write a Ruby class that performs this operation:
+
+      
+      <pre>
+        class Adder
+
+          def add( a, b )
+            a.to_f + b.to_f
+          end
+
+        end
+      </pre>
+
+
+      (Just to give this example a little more value, we'll have it explicitly convert its
+      operands to floats--it makes things a little more impressive.)
+
+
+      Save your file as "tutorial.rb" and move on to the next step.
+
+    - >
+      h3. Tell Copland About It
+
+
+      Next, we need to tell Copland about our service. We'll create a package descriptor file
+      (called "package.yml") in the same directory as our "tutorial.rb" file, and in it we'll
+      tell Copland the name of our service and what Ruby class implements it (among other
+      things). This file is YAML-formatted, so if you've used YAML before, the format (at
+      least) should look very familiar.
+
+
+      <pre>
+       ---
+        id: tutorial
+        description: This is the package for the Copland tutorials.
+
+        service-points:
+
+          Adder:
+            description: A service for adding two numbers.
+            implementor: tutorial/Adder
+      </pre>
+
+
+      (The 'description' elements are always optional... we've shown them here just to
+      demonstrate how they are used, but in later tutorials we'll leave them out, for
+      clarity.)
+
+
+      This descriptor creates a new _package_, called "tutorial". In Copland, all services
+      are defined within _packages_.
+      
+      The descriptor then defines a single _service point_, called Adder. (Service points
+      are the definitions of services. You can think of it like this: just as an object is
+      the instantiation of a class, so is a service the instantiation of a service point.)
+      This service point is implemented by "tutorial/Adder", which means that "tutorial"
+      will be @require@d, and then "Adder" instantiated.
+
+    - >
+      h3. Use the Service
+
+
+      Lastly, we create a "main.rb" driver file which we'll use to test our new service point.
+      This driver will simply instantiate a registry, grab a reference to the new service, and
+      then invoke our @#add@ method:
+
+
+      <pre>
+        require 'copland'
+
+        registry = Copland::Registry.build
+
+        adder = registry.service( "tutorial.Adder" )
+
+        puts adder.add( "5", 7 )
+      </pre>
+
+
+      The @#build@ method of Copland::Registry will recursively search for package descriptor
+      files. By default, it will search from the current directory (but you can specify a
+      different directory by giving it as a parameter to @#build@).
+
+
+      Once the registry has been initialized, you can query it for services. In this case, we
+      ask the registry for the @tutorial.Adder@ service (i.e., the @Adder@ service that exists
+      in the @tutorial@ package). Copland then returns this service.
+
+
+      Lastly, we invoke the @#add@ method and print the result. And it just works!
+
+    summary: >-
+      This tutorial demonstrated a few things:
+
+
+      # Copland services are just plain-ol' Ruby objects.
+
+      # Package descriptors are just YAML files
+
+      # Registry instantiation and querying services
+
+
+      Also, this tutorial used the _simple_ implementor; all it did was accept a class name
+      (and @require@ path) and instantiate it. Although this is useful for simple services,
+      it doesn't give us the _dependency injection_ that IoC containers are famous for. The
+      next tutorial will show how to wire several services together automatically, using the
+      _complex_ implementor.
+
+- Service Factories:
+    brief: >-
+      Introduces the concept of a "service factory", and shows how to use them to
+      create complex services.
+
+    intro: >-
+      As you saw in the last tutorial, you can create services by mapping them directly to
+      Ruby classes. The last tutorial used the _simple_ implementor to do this, which has
+      its limitations. For one, the class must have a no-argument constructor, which restricts
+      what classes you can use with it.
+
+
+      This tutorial will demonstrate the use of _service factories_ to perform more complex
+      styles of instantiation and initialization.
+
+
+      A _service factory_ is just a special kind of service that is used to create other
+      services. There are several different service factories that Copland provides by default;
+      this tutorial will only use the BuilderFactory.
+
+
+      This tutorial will continue the application started in the first tutorial. We'll extend
+      the "adder" example into a simple calculator object that delegates its operations to
+      different services.
+
+    steps:
+    - >-
+      h3. Implement the Services
+
+
+      Most calculators support at least four operations: addition, multiplication, division,
+      and subtraction. We've already got a service that does addition: let's write three
+      more that do the multiplication, division, and subtraction:
+
+
+      <pre>
+        class Subtractor
+          def subtract( a, b )
+            a.to_f - b.to_f
+          end
+        end
+
+        class Multiplier
+          def multiply( a, b )
+            a.to_f * b.to_f
+          end
+        end
+
+        class Divider
+          def divide( a, b )
+            a.to_f / b.to_f
+          end
+        end
+      </pre>
+
+
+      Lastly, we'll create our calculator class:
+
+
+      <pre>
+        class Calculator
+          attr_writer :adder
+          attr_writer :subtractor
+          attr_writer :multiplier
+          attr_writer :divider
+
+          def add( a, b )
+            @adder.add( a, b )
+          end
+
+          def subtract( a, b )
+            @subtractor.subtract( a, b )
+          end
+
+          def multiply( a, b )
+            @multiplier.multiply( a, b )
+          end
+
+          def divide( a, b )
+            @divider.divide( a, b )
+          end
+        end
+      </pre>
+
+
+      Notice that we never instantiate any of the delegate classes: we're going to
+      leave that up to Copland. Instead, we simply provide some setters, which
+      Copland will use to set those dependencies. (Note that these setters can also
+      aid in unit testing, since you can easily set each of those properties to
+      some mock object. We won't demonstrate that, though, since unit testing is
+      beyond the scope of this tutorial.)
+
+    - >-
+      h3. Package Descriptor
+
+
+      We now add to our package descriptor. Just as we defined a service point for
+      the Adder class, we now have to add service points for each of the other
+      classes we created.
+      
+
+      The Subtractor, Multiplier, and Divider service points will look very much
+      like the Adder service point. Each uses the _simple_ implementor.
+
+
+      <pre>
+        Subtractor:
+          implementor: tutorial/Subtractor
+
+        Multiplier:
+          implementor: tutorial/Multiplier
+
+        Divider:
+          implementor: tutorial/Divider
+      </pre>
+
+
+      The Calculator service point, however, is a bit more complicated. Not only
+      do we need to say what class implements the service, but we also need to
+      say what services get wired into it for each of its properties. To do this,
+      we'll use the @copland.BuilderFactory@ service.
+
+
+      <pre>
+        Calculator:
+          implementor:
+            factory: copland.BuilderFactory
+            class: tutorial/Calculator
+            properties:
+              adder: !!service tutorial.Adder
+              subtractor: !!service tutorial.Subtractor
+              divider: !!service tutorial.Divider
+              multiplier: !!service tutorial.Multiplier
+      </pre>
+
+
+      The @implementor@ section, in this case, is a map, instead of a string.
+      The map specifies the service _factory_ to use (@copland.BuilderFactory@,
+      in this case), the _class_ that will implement the service, and the
+      properties that will be set. (Note that if you are using @copland.BuilderFactory@
+      as your service factory, you can omit the @factory@ element. It is retained
+      explicitly for this tutorial to demonstrate the use of the @factory@ element.)
+
+
+      Note the special syntax of the properties: that @!!service@ bit says that
+      the following name is the name of a service point that should be instantiated
+      and passed as the value of the corresponding property. In other words, when the
+      BuilderFactory instantiates the Calculator class, it will also obtain references
+      to the Adder, Subtractor, Divider, and Multiplier services, and wire them into
+      the appropriate properties of the new Calculator object.
+
+
+      Lastly, note that we used the fully-qualified service names for the dependencies
+      (i.e., "tutorial.Adder"). Because the Calculator service point is in the same
+      package as the dependencies, we could have simply given the names of the service
+      points, unqualified (without the package names).
+
+    - >
+      h3. Putting it all Together
+
+
+      We'll modify the "main.rb" driver file slightly, to test our new Calculator
+      service:
+
+
+      <pre>
+        require 'copland'
+
+        registry = Copland::Registry.build
+
+        calc = registry.service( "tutorial.Calculator" )
+
+        puts calc.add( "5", 7 )
+        puts calc.subtract( "5", 7 )
+        puts calc.multiply( "5", 7 )
+        puts calc.divide( "5", 7 )
+      </pre>
+
+
+      Once run, you should see the program spit out the answers, as you would expect.
+
+
+    summary: >-
+      This tutorial showed you how to use more complicated implementors. In particular, it
+      showed you how to have Copland automatically wire dependencies together, instantiating
+      services as needed. However, you only saw how to use properties to wire services
+      together; you can also specify constructor parameters that will be passed to the new
+      service when it is instantiated.
+
+
+      You also saw how to use the @!!service@ directive, to instruct Copland to interpret a
+      value as a service point name, instead of simply as a string. There are several such
+      directives; see the Copland documentation for a comprehensive list.
+
+- Service Models:
+    brief: >-
+      Introduces the concept of the "service model", and shows the difference between
+      "singleton" and "prototype".
+
+    intro: >-
+      Let's take our calculator example one step further and add a "memory" function.
+      By storing a value into the memory, you can then call the various operators
+      with only one parameter, and have them operate on the remembered value.
+
+
+      Sound cool? It's also pretty easy! Here goes...
+
+    steps:
+      - >-
+        h3. Add the Memory
+
+
+        First, we need to modify the calculator to hack in support for memory. This
+        involves adding an instance variable and two methods, getters and setters
+        for that variable:
+
+
+        <pre>
+          attr_accessor :memory
+        </pre>
+
+
+        We don't worry about initializing the corresponding instance variable in
+        the code--that's more properly a task for the IoC container. We just edit
+        the "package.yml" file and add another property initializer to the
+        Calculator service:
+
+
+        <pre>
+          Calculator:
+            implementor:
+              factory: copland.BuilderFactory
+              class: tutorial/Calculator
+              properties:
+                adder: !!service Adder
+                subtractor: !!service Subtractor
+                divider: !!service Divider
+                multiplier: !!service Multiplier
+                memory: 0
+        </pre>
+
+
+        This then says then when constructing a Calculator service, always set
+        the memory property to 0.
+
+      - >-
+        h3. Modify the Operators
+
+
+        Next, we need to modify the operators so that they each treat the second
+        parameter as optional, defaulting to our memory variable:
+
+
+        <pre>
+          def add( a, b=memory )
+            @adder.add( a, b )
+          end
+
+          def subtract( a, b=memory )
+            @subtractor.subtract( a, b )
+          end
+
+          def multiply( a, b=memory )
+            @multiplier.multiply( a, b )
+          end
+
+          def divide( a, b=memory )
+            @divider.divide( a, b )
+          end
+        </pre>
+
+      - >-
+        h3. Play
+
+
+        We can now try it by doing multiples and powers of 5. Edit our "main.rb" driver file
+        to look something like this:
+
+
+        <pre>
+          require 'copland'
+
+          registry = Copland::Registry.build
+
+          calc = registry.service( "tutorial.Calculator" )
+
+          puts "Multiples of 5:"
+          10.times do
+            puts calc.memory
+            calc.memory = calc.add( 5 )
+          end
+
+          calc.memory = 1.0
+
+          puts
+          puts "Powers of 5:"
+          10.times do
+            puts calc.memory
+            calc.memory = calc.multiply( 5 )
+          end
+        </pre>
+
+
+        When run, it should spit out a list of the multiples of five, and the powers of five!
+        Slick, huh?
+
+
+        But wait! Let's try another trick--let's get TWO calculators going at once and have
+        them each dealing with a different base. Should be pretty straightforward to do; 
+        perhaps something like this:
+
+
+        <pre>
+          require 'copland'
+
+          registry = Copland::Registry.build
+
+          calc1 = registry.service( "tutorial.Calculator" )
+          calc2 = registry.service( "tutorial.Calculator" )
+
+          puts "Multiples:"
+          10.times do
+            puts "#{calc1.memory}\t#{calc2.memory}"
+            calc1.memory = calc1.add( 5 )
+            calc2.memory = calc2.add( 2 )
+          end
+
+          calc1.memory = 1.0
+          calc2.memory = 1.0
+
+          puts
+          puts "Powers:"
+          10.times do
+            puts "#{calc1.memory}\t#{calc2.memory}"
+            calc1.memory = calc1.multiply( 5 )
+            calc2.memory = calc2.multiply( 2 )
+          end
+        </pre>
+
+
+        We save it, run it, and--_what?!?_ We're getting multiples of 7 and powers of 10,
+        for each column... Huh?!?
+
+      - >-
+        h3. Diagnosing the Problem
+
+
+        What's happening is this: because you haven't specified a _service model_ for the Calculator
+        service point, the default model (@singleton-deferred@) is being used. Both the
+        @singleton@ and @singleton-deferred@ models are alike in that anytime you request
+        an instance of a service point that uses one of those models, you get _the exact same
+        instance back_. Just like "instantiating" a singleton class.
+
+
+        That's right. When we requested two instances of the Calculator service, we were actually
+        getting two references to the _same instance_, instead. Thus, each iteration through
+        the "multiples" loop was adding 5+2=7 to the memory, and each iteration through the
+        "powers" loop was multiply 5*2=10 by the memory.
+
+
+        Huh. Okay, so we know the problem. How do we get the behavior we wanted?
+
+      - >-
+        h3. Fixing the Problem
+
+
+        So we understand _why_ the problem is happening. But how do we fix it?
+
+
+        Well, first let's understand about service models. The service model is what controls
+        _when_ a service point is instantiated. For the singleton models, the service point
+        is only instantiated once--the first time it is requested. What we want is a service
+        model that will instantiate the service point _every_ time we request it.
+
+
+        We're in luck. There is just such a service model: _prototype_. By setting the
+        service model to @prototype@, we'll cause each request for the @calc.Calculator@
+        service to return a new instance of the Calculator class.  Just set the model
+        by specifying the @model@ element in your service point descriptor (in the
+        @package.yml@ file):
+
+
+        <pre>
+          Calculator:
+            model: prototype
+            implementor:
+              ...
+        </pre>
+
+
+        Save your file, and run your "main.rb" script again--the output should look much
+        better!
+
+    summary: >-
+      In this tutorial, you learned:
+
+
+      # The default service model for a service is @singleton-deferred@. This model (and it's
+      cousin, the @singleton@ service model) both cause a service point to be instantiated
+      only the first time the service is requested.
+
+      # To get a service point that is instantiated _every_ time it is requested, use the
+      @prototype@ service model.
+
+
+      In general, use the @prototype@ model (or possibly the @threaded@ model) when you have
+      a service that remembers some kind of state. For stateless services, the @singleton@
+      models are appropriate.
+
+
+      Some models are _deferring_ models. This means that the service is not actually constructed
+      until the first time a method is invoked on the new service. The difference is subtle, but
+      important: @singleton@ and @singleton-deferred@ are identical, except with @singleton@
+      the service is constructed as soon as it is requested, whereas with @singleton-deferred@,
+      the service won't actually be constructed until the last possible moment, when you need to
+      invoke a method of the service.
+
+
+      Likewise, there is a @prototype-deferred@ model, to compliment the @prototype@ model.
+
+
+      The only other standard service model is the @threaded@ model, which constructs a new
+      instance of the service for each thread that requests it. In that way, it is like a cross
+      between the @singleton@ and @prototype@ models.
+
+- Logging Interceptor:
+    brief: >-
+      Shows how to use the logging interceptor to add logging for method invocations
+      on any service.
+
+    intro: >-
+      Sometimes (particularly when debugging) you want to be able to trace your program's
+      execution. You want to see when certain methods are being invoked, and with what parameters,
+      and what the return values are. If an exception is being raised, you'd like to see that,
+      too.
+
+
+      Although the calculator example we've been using up to this point is trivial enough that
+      there's really no need for such tracing, it is an easy one to demonstrate it on. So,
+      let's take the code we wrote for the last tutorial and add logging, just for the halibut.
+
+
+      What we'll do is modify the program so that it logs everytime a method of
+      the Calculator or Adder services is invoked from outside the service.
+
+    steps:
+      - >-
+        h3. copland.LoggingInterceptor
+
+
+        _Interceptors_ are another kind of service, similar to factory services, that Copland
+        uses to _intercept_ method calls. An instance of the interceptor service sits
+        (conceptually) between the caller and the method, and acts as a filter for everything
+        going into or out of the method.
+
+
+        There is currently only one interceptor that ships with Copland--copland.LoggingInterceptor. 
+        It sits between the caller and the method and happily logs away, noting the parameters,
+        return values, and exceptions that are raised.
+
+      - >-
+        h3. Adding the Interceptor
+
+
+        Here we get to demonstrate one of (in my opinion) the "coolest" aspects of Copland.
+        We can add the logging solely by editing our package descriptor--_nothing else needs
+        to change!_ Our Ruby objects remain blissfully ignorant that the logging has been
+        added. Slick, huh?
+
+
+        So, let's open our package descriptor and add the interceptor to the Adder service
+        first:
+
+
+        <pre>
+          Adder:
+            implementor: tutorial/Adder
+            interceptors:
+              - service: copland.LoggingInterceptor
+        </pre>
+
+
+        The @interceptors@ element is always a list of interceptors that should be added
+        to the service. (By default, the interceptors will be invoked in the order they
+        were added. You can change this, but it's a bit beyond the scope of this tutorial.)
+        Each element of the list _must_ be a hash, each with the _service_ element (at
+        least) defined. That element must name a valid interceptor service. In this case,
+        the interceptor service is copland.LoggingInterceptor.
+
+
+        Now, let's add the logging interceptor to the Calculator service:
+
+
+        <pre>
+          Calculator:
+            interceptors:
+              - service: copland.LoggingInterceptor
+            ...
+        </pre>
+
+
+        Note that it is not important _where_ the @interceptors@ element appears in the
+        service point--just as long as it appears at the "top level" of the service point
+        definition.
+
+      - >-
+        h3. Running the Program
+
+
+        So, we've got the interceptors in place now. Let's try running the program and
+        seeing what happens!
+
+
+        You should see the exact same output from the last tutorial--the list of multiples
+        and powers. However, there should be a file named "copland.log" in the same
+        directory. This file has been appearing every time you've run your programs during
+        these tutorials, but it has been largely empty because nothing has been logged. This
+        time, however, there will be quite a bit of text in the log, looking something
+        like this:
+
+
+        <pre>
+          # Logfile created on Sat Sep 04 09:29:58 MDT 2004 by logger.rb/1.5.2.4
+          D, [2004-09-04T09:29:58.963327 #23288] DEBUG -- tutorial.Calculator: memory(  )
+          D, [2004-09-04T09:29:58.963471 #23288] DEBUG -- tutorial.Calculator: memory => 0
+          D, [2004-09-04T09:29:58.963522 #23288] DEBUG -- tutorial.Calculator: memory(  )
+          D, [2004-09-04T09:29:58.963564 #23288] DEBUG -- tutorial.Calculator: memory => 0
+          D, [2004-09-04T09:29:58.963651 #23288] DEBUG -- tutorial.Calculator: add( 5 )
+          D, [2004-09-04T09:29:58.999262 #23288] DEBUG -- tutorial.Adder: add( 5, 0 )
+          D, [2004-09-04T09:29:58.999486 #23288] DEBUG -- tutorial.Adder: add => 5.0
+          D, [2004-09-04T09:29:58.999547 #23288] DEBUG -- tutorial.Calculator: add => 5.0
+          D, [2004-09-04T09:29:58.999617 #23288] DEBUG -- tutorial.Calculator: memory=( 5.0 )
+          D, [2004-09-04T09:29:58.999663 #23288] DEBUG -- tutorial.Calculator: memory= => 5.0
+          ...
+        </pre>
+
+
+        Let's analyze the output a bit. First, it's saying that the @#memory@ method
+        was invoked, with no parameters, and that it returned 0. Then, it was invoked
+        again, and returned 0 again. (This is because we've got two calculators going
+        at once, both of them logging their method invocations.) Next, @#add@ was
+        invoked, with a parameter of 5. Then, the Adder's @#add@ is invoked, with two
+        parameters (5, and 0). That method then returns a value of 5.0, followed by the
+        Calculator's @#add@ method returning 5.0. Then, the @#memory=@ method is invoked,
+        with a value of 5.0, which it also returns.
+
+
+        That's a bit more verbose than we intended--for example, we didn't really care to
+        see all the @memory@ method invocations. We'd like to be able to _exclude_ those
+        methods from the logger.
+
+      - >-
+        h3. Excluding Methods
+
+
+        The LoggingInterceptor supports (among others) two parameters, @exclude@ and
+        @include@. Each of these elements is an array of special regular expressions
+        that should match method names.
+
+
+        By default, all methods are included. If you specify a set of @exclude@ patterns,
+        any method that matches any one of those patterns will be excluded from
+        consideration. If you further specify a set of @include@ patterns, then any
+        method that has been excluded from consideration, and which matches any one of
+        the @include@ patterns, will be reincluded for consideration.
+
+
+        So, let's exclude the @#memory@ and @#memory=@ methods from the Calculator's
+        logging interceptor. We can do it by name each method explicitly, like this:
+
+
+        <pre>
+          Calculator:
+            interceptors:
+              - service: copland.LoggingInterceptor
+                exclude:
+                  - memory
+                  - memory=
+            ...
+        </pre>
+
+
+        Or, we can be a little more concise and use regular expressions:
+
+        <pre>
+          Calculator:
+            interceptors:
+              - service: copland.LoggingInterceptor
+                exclude:
+                  - memory=?
+            ...
+        </pre>
+
+
+        Delete the original copland.log (otherwise subsequent runs will just append to
+        it) and then rerun your script. None of the @memory@ methods are being logged!
+        Much better.
+
+    summary: >-
+      In this tutorial you learned how to apply a logging interceptor to a service.
+      You also learned how to exclude certain methods from being logged.
+
+
+      Note that you can easily specify that only certain methods should be logged (instead
+      of the reverse, where only certain methods should _not_ be logged). To
+      do this, first exclude all methods (with a ".*" regular expression), and then
+      explicitly include the methods you want to log.
+
+
+      Also, it should be noted that the regular expressions for the include and exclude
+      patterns are special: you can also specify the _arity_ of the methods that should
+      be included or excluded. For example, if you want to exclude all methods that are
+      invoked with 3 parameters, you could do:
+
+
+      <pre>
+        exclude:
+          - .*(3)
+      </pre>
+
+
+      If you prefix the arity number with a comparison operator (less-than or greater-than),
+      you can exclude (or include) methods that are invoked with less than or greater than that
+      number of parameters:
+
+
+      <pre>
+        exclude:
+          - .*(>3)
+        include:
+          - .*(5)
+      </pre>
+
+
+      The above would exclude any method invoked with more than three parameters, unless it
+      was invoked with exactly five parameters.
+
+- Configuration Points:
+    brief: >-
+      Demonstrates the use of configuration points for decentralizing service configuration.
+
+    intro: >-
+      Suppose, next, we want to add the ability to register new functions with the calculator,
+      so that third parties that wish to reuse our snappy little number cruncher can add their
+      own custom operations.
+
+
+      Think for a minute how you would solve this. There are several approaches that could
+      be taken, none of them necessarily any better or worse than the other. The drawback
+      for each of them is that _you would have to implement the infrastructure yourself_.
+      
+
+      Copland provides a ready-made package-centric configuration infrastructure, which
+      (as you will see) allows any package to contribute configuration data to
+      configuration points in any other package.
+
+    steps:
+      - >-
+        h3. Modify Calculator
+
+
+        First, let's modify our Calculator class again. We'll add _another_ writer
+        attribute, called @functions@, which we'll assume will always be a Hash (or
+        Hash-like) object. Each pair in the hash will be a named object that implements
+        the @:compute@ message.
+
+
+        <pre>
+          class Calculator
+            attr_writer :adder
+            attr_writer :subtractor
+            ...
+            attr_writer :functions
+        </pre>
+
+
+        Then, we'll implement a new method on Calculator, called @function@, which allows
+        clients to specify a function to execute and the arguments to give it. We won't
+        bother with error checking:
+
+
+        <pre>
+          def function( name, *arguments )
+            @functions[ name ].compute( *arguments )
+          end
+        </pre>
+
+      - >-
+        h3. Create a Configuration Point
+
+
+        Next, we'll create a configuration point. A configuration point may be either
+        a _list_, or a _map_. We want a map, so that it will work nicely as a lookup for
+        function services.
+
+
+        Configuration points are defined in their own section of the package descriptor,
+        under the @configuration-points@ key. Thus:
+
+
+        <pre>
+          id: tutorial
+
+          service-points:
+            ...
+
+          configuration-points:
+
+            CalculatorFunctions:
+              type: map
+        </pre>
+
+
+        This creates a new (and empty) configuration point, called CalculatorFunctions.
+        It is of type "map", which means it quacks like a Hash. Since it belongs to the
+        tutorial package, its fully qualified name is "tutorial.CalculatorFunctions".
+
+
+        For now, we'll leave it empty. We'll contribute values to it in a little bit.
+
+      - >-
+        h3. Edit the Calculator Service Point
+
+
+        Now, we edit the service point that defines our Calculator service. Specifically,
+        we add another property initializer:
+
+
+        <pre>
+          Calculator:
+            model: prototype
+            implementor:
+              factory: copland.BuilderFactory
+              class: tutorial/Calculator
+              properties:
+                adder: !!service Adder
+                ...
+                functions: !!configuration CalculatorFunctions
+        </pre>
+
+
+        Here, we're telling Copland to associate the CalculatorFunctions configuration point
+        with the @functions@ property of our Calculator.
+
+
+        This means that anything any package adds to that configuration point is going to
+        be visible to our Calculator, via its @functions@ property. The only part we're
+        missing, then, is what goes into that configuration point.
+
+
+      - >-
+        h3. Prepare to Create the @tutorial.functions@ Package
+
+
+        Just to keep things nice and neat, we'll create another package in which we'll
+        define our "custom" calculator functions.
+
+
+        Create a new subdirectory in the same directory as your calculator implementation.
+        Call it @functions@. Then change to that directory.
+
+
+        <pre>
+          $ mkdir functions
+          $ cd functions
+        </pre>
+
+      - >-
+        h3. Implement Some Functions
+
+
+        We need to decide which custom functions to implement. I'll arbitrarily recommend
+        the trigonometric "sin" function, and the natural logarithm, mostly because they're
+        fun to say, but also because they're two of many available functions that Ruby
+        already provides us implementations for.
+
+
+        So, let's create a "services.rb" file in our new "functions" subdirectory. We'll
+        implement two classes, one for each new function. Each class only has to respond
+        to the "compute" message, accepting the expected parameters and returning the
+        computed result. Thus:
+
+
+        <pre>
+          class Sine
+
+            def compute( a )
+              Math.sin( a )
+            end
+
+          end
+
+          class NaturalLogarithm
+
+            def compute( n )
+              Math.log( n )
+            end
+
+          end
+        </pre>
+
+      - >-
+        h3. Define the Service Points
+
+
+        Now, we create the package descriptor for our new package. Create a new file called
+        "package.yml" in the "functions" subdirectory:
+
+
+        <pre>
+          ---
+          id: tutorial.functions
+
+          service-points:
+
+            Sine:
+              implementor: functions/services/Sine
+
+            NaturalLogarithm:
+              implementor: functions/services/NaturalLogarithm
+        </pre>
+
+
+        Note the name of the package: @tutorial.functions@. This is the recommended way of
+        naming your packages, with names of subpackages including the names of their
+        ancestor packages. However, you are in no way constrained to name them this way--Copland
+        does not enforce it.
+
+      - >-
+        h3. Contribute the Services to the Configuration Point
+
+
+        Next, we tie it all together. Our @tutorial.functions@ package needs to contribute
+        the two services it defines to the @tutorial.CalculatorFunctions@ configuration point.
+        This way, when the Calculator service is instantiated, it will come ready-made with
+        a map of all functions that other packages want to be made available.
+
+
+        Contributes are made in the @contributions@ section of the package descriptor. Just
+        specify the name of the configuration point to contribute to, and then the values
+        you want to contribute. For configuration points of type list, the values should be
+        formatted as a list. For maps, the values should be formatted as a map.
+
+
+        <pre>
+          id: tutorial.functions
+
+          service-points:
+            ...
+
+          contributions:
+
+            tutorial.CalculatorFunctions:
+              sin: !!service Sine
+              ln: !!service NaturalLogarithm
+        </pre>
+
+
+        Here we've registered the Sine service under the name "sin", and the NaturalLogarithm
+        service under the name "ln".
+
+      - >-
+        h3. Put it Together
+
+
+        Now, in our "main.rb" driver file, we just need to call our new @function@ interface
+        and see if it really works:
+
+
+        <pre>
+          require 'copland'
+
+          registry = Copland::Registry.build
+
+          calc = registry.service( "tutorial.Calculator" )
+
+          puts "sin(pi/4) = #{calc.function( "sin", Math::PI/4 )}"
+          puts "ln(e^3) = #{calc.function( "ln", Math::E ** 3 )}"
+
+          registry.shutdown
+        </pre>
+
+
+        If all was done correctly, you should see the following output:
+
+
+        <pre>
+          $ ruby main.rb
+          sin(pi/4) = 0.707106781186547
+          ln(e^3) = 3.0
+        </pre>
+
+    summary: >-
+      The following techniques were demonstrated in this tutorial:
+
+
+      # Applications with multiple Copland packages
+
+      # Creating a configuration point
+
+      # Contributing to a configuration point
+
+      # Associating a configuration point with a property of a service
+      
+
+      Additionally, you saw that subdirectories would (by default) be recursively
+      searched for package descriptors.
+
+
+      Play with this tutorial some more. Try adding some more functions. Try adding
+      some more packages that contribute to the @tutorial.CalculatorFunctions@
+      configuration point. The more you use these features, the better you'll understand
+      them.