RubyGems - needle - Versions diffs - 1.2.0 → 1.2.1 - Mend

needle 1.2.0 → 1.2.1

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

Files changed (46) hide show

data/doc/manual-html/chapter-1.html +138 -78
data/doc/manual-html/chapter-2.html +180 -99
data/doc/manual-html/chapter-3.html +111 -75
data/doc/manual-html/chapter-4.html +80 -48
data/doc/manual-html/chapter-5.html +106 -56
data/doc/manual-html/chapter-6.html +82 -34
data/doc/manual-html/chapter-7.html +74 -38
data/doc/manual-html/chapter-8.html +70 -41
data/doc/manual-html/chapter-9.html +88 -63
data/doc/manual-html/index.html +6 -6
data/doc/manual-html/needle.png +0 -0
data/doc/manual-html/{manual.css → stylesheets/manual.css} +83 -10
data/doc/manual-html/stylesheets/ruby.css +17 -0
data/doc/manual/chapter.erb +20 -0
data/doc/manual/img/Needle.ai +0 -0
data/doc/manual/img/needle.png +0 -0
data/doc/manual/manual.rb +80 -5
data/doc/manual/manual.yml +3 -3
data/doc/manual/page.erb +1 -1
data/doc/manual/parts/01_use_cases.txt +70 -70
data/doc/manual/parts/02_creating.txt +19 -19
data/doc/manual/parts/02_namespaces.txt +29 -29
data/doc/manual/parts/02_services.txt +40 -41
data/doc/manual/parts/03_conventional.txt +20 -20
data/doc/manual/parts/03_locator.txt +44 -44
data/doc/manual/parts/04_overview.txt +1 -1
data/doc/manual/parts/04_setup.txt +32 -32
data/doc/manual/parts/customizing_contexts.txt +14 -14
data/doc/manual/parts/customizing_interceptors.txt +25 -25
data/doc/manual/parts/customizing_namespaces.txt +12 -12
data/doc/manual/parts/interceptors_attaching.txt +29 -30
data/doc/manual/parts/interceptors_custom.txt +16 -16
data/doc/manual/parts/interceptors_ordering.txt +5 -5
data/doc/manual/parts/libraries_creating.txt +18 -18
data/doc/manual/parts/libraries_using.txt +19 -19
data/doc/manual/parts/logging_configuration.txt +13 -13
data/doc/manual/parts/logging_logfactory.txt +21 -22
data/doc/manual/parts/models_models.txt +8 -8
data/doc/manual/parts/models_overview.txt +1 -1
data/doc/manual/parts/models_pipelines.txt +22 -22
data/doc/manual/{manual.css → stylesheets/manual.css} +83 -10
data/doc/manual/stylesheets/ruby.css +17 -0
data/lib/needle/definition-context.rb +3 -2
data/lib/needle/lifecycle/proxy.rb +1 -1
data/lib/needle/version.rb +1 -1
metadata +94 -85

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

@@ -1,7 +1,7 @@
 <html>
   <head>
     <title>Needle Manual :: Chapter 6: Service Models</title>
-    <link type="text/css" rel="stylesheet" href="manual.css" />
+    <link type="text/css" rel="stylesheet" href="stylesheets/manual.css" />
   </head>
   <body>
@@ -14,8 +14,8 @@
           </div>
         </td><td valign='middle' align='right'>
           <div class="info">
-            Needle Version: <strong>1.2.0</strong><br />
-            Manual Last Updated: <strong>2004-11-18 15:36 GMT</strong>
+            Needle Version: <strong>1.2.1</strong><br />
+            Manual Last Updated: <strong>2005-07-27 05:49 UTC</strong>
           </div>
         </td></tr>
       </table>
@@ -208,7 +208,17 @@
         <div id="content">
-          <h1>6. Service Models</h1>
+           <div class="top"><div class="prevnext">
+    <a href="chapter-5.html">Previous (5. Interceptors)</a> |
+  <a href="index.html">Up</a>
+    | <a href="chapter-7.html">Next (7. Logging)</a>
+</div></div>
+<h1>6. Service Models</h1>
@@ -220,7 +230,8 @@
    <div class="section">
-     <p>Service models are the mechanism by which a client can specify how the lifecycle of a particular service should be managed. By default, all services are managed as <em>singletons</em>, but it is a simple matter to choose a different behavior when a service is registered.</p>
+     <p>Service models are the mechanism by which a client can specify how the lifestyle of a particular service should be managed. By default, all services are managed as <em>singletons</em>, but it is a simple matter to choose a different behavior when a service is registered.</p>
 	<p>Underneath, service models are implemented using an <em>instantiation pipeline</em>.</p>
    </div>
@@ -237,11 +248,16 @@
    <div class="section">
      <p>An <em>instantiation pipeline</em> is a sequence of elements, each of which knows how to perform some aspect of the instantiation of a service.</p>
-	<p>Every service consists of at least one instantiation element&#8212;the block that was given when the service was registered. Other elements may be combined with this block to enforce various aspects of lifecycle management, such as <em>multiplicity</em> (singleton vs. prototype) and <em>laziness</em> (deferred vs. immediate instantiation).</p>
+	<p>Every service consists of at least one instantiation element&#8212;the block that was given when the service was registered. Other elements may be combined with this block to enforce various aspects of lifestyle management, such as <em>multiplicity</em> (singleton vs. prototype) and <em>laziness</em> (deferred vs. immediate instantiation).</p>
 	<h3>Standard Pipeline Elements</h3>
-	<p>There are five standard pipeline elements available in Needle (although you may certainly create your own):</p>
+	<p>There are six standard pipeline elements available in Needle (although you may certainly create your own):</p>
 	<ul>
 	<li><code>deferred</code>: this will always return a proxy that wraps subsequent pipeline elements, causing the subsequent elements to be executed only when a method is invoked on the proxy (at which point the method is then delegated to the resulting service).</li>
 		<li><code>initialize</code>: this will invoke a method on the resulting service (defaults to <code>initialize_service</code>, though it can be changed). It is used for doing final initialization of services (for services that need it).</li>
@@ -251,56 +267,71 @@
 		<li><code>threaded</code>: this is like the <code>singleton</code> element, but it ensures that a service is instantiated no more than once <em>per thread</em>.</li>
 	</ul>
 	<h3>Priorities</h3>
 	<p>Just like interceptors, pipeline elements have priorities as well. These priorities determine the order in which the elements are executed in the pipeline.</p>
 	<p>Each element type has a default priority, although that priority can be overridden when the element is added to the pipeline.</p>
 	<h3>Custom Pipeline Elements</h3>
 	<p>Creating new pipeline elements simple. Just create a new class that extends <code>Needle::Pipeline::Element</code>. Set the default pipeline priority (using the <code>#set_default_priority</code> class method), and then implement the <code>#call</code> method (accepting at least two parameters: the container and the service point).</p>
-<pre>
-  require 'needle/pipeline/element'
+	<div class='figure'>
+<span class='caption'>Custom pipeline element example [ruby]</span>
+<div class='body'><table border='0' cellpadding='0' cellspacing='0'><tr><td class='lineno'>1<br />2<br />3<br />4<br />5<br />6<br />7<br />8<br />9<br />10<br />11<br />12<br /></td><td width='100%'><link rel='stylesheet' type='text/css' href='stylesheets/ruby.css' /><div class='ruby'><pre><span class="ident">require</span> <span class="punct">'</span><span class="string">needle/pipeline/element</span><span class="punct">'</span>
+<span class="keyword">class </span><span class="class">MyPipelineElement</span> <span class="punct">&lt;</span> <span class="constant">Needle</span><span class="punct">::</span><span class="constant">Pipeline</span><span class="punct">::</span><span class="constant">Element</span>
+  <span class="ident">set_default_priority</span> <span class="number">50</span>
+  <span class="keyword">def </span><span class="method">call</span><span class="punct">(</span> <span class="ident">container</span><span class="punct">,</span> <span class="ident">point</span><span class="punct">,</span> <span class="punct">*</span><span class="ident">args</span> <span class="punct">)</span>
+    <span class="punct">...</span>
+    <span class="ident">result</span> <span class="punct">=</span> <span class="ident">succ</span><span class="punct">.</span><span class="ident">call</span><span class="punct">(</span> <span class="ident">container</span><span class="punct">,</span> <span class="ident">point</span><span class="punct">,</span> <span class="punct">*</span><span class="ident">args</span> <span class="punct">)</span>
+    <span class="punct">...</span>
+    <span class="keyword">return</span> <span class="ident">result</span>
+  <span class="keyword">end</span>
+<span class="keyword">end</span></pre></div></td></tr></table></div></div>
-  class MyPipelineElement &lt; Needle::Pipeline::Element
-    set_default_priority 50
-    def call( container, point, *args )
-      ...
-      result = succ.call( container, point, *args )
-      ...
-      return result
-    end
-  end
-</pre>
 	<p>To invoke the next element of the pipeline, just invoke <code>#succ.call(...)</code>.</p>
 	<p>If needed, you can also implement <code>#initialize_element</code> (with no arguments), which you may invoke to perform initialization of the element. From there, you can access the options that were given to the element via the <code>#options</code> accessor.</p>
 	<p>See the implementations of the existing elements in <code>needle/lifecycle</code> for examples.</p>
 	<h3>Added Pipelines Elements to Services</h3>
 	<p>You can specify the pipeline elements to use for a service via the <code>:pipeline</code> option. This must refer to an array, each element of which must be either a symbol (in which case it references an element of the <code>:pipeline_elements</code> service), or a class (in which case it must implement the interface required by @Needle::Pipeline::Element).</p>
-<pre>
-  reg.register( :foo, :pipeline =&gt; [ :singleton, MyPipelineElement ] ) { ... }
-</pre>
+	<div class='figure'>
+<span class='caption'>Adding pipelines to services [ruby]</span>
+<div class='body'><link rel='stylesheet' type='text/css' href='stylesheets/ruby.css' /><div class='ruby'><pre><span class="ident">reg</span><span class="punct">.</span><span class="ident">register</span><span class="punct">(</span> <span class="symbol">:foo</span><span class="punct">,</span> <span class="symbol">:pipeline</span> <span class="punct">=&gt;</span> <span class="punct">[</span> <span class="symbol">:singleton</span><span class="punct">,</span> <span class="constant">MyPipelineElement</span> <span class="punct">]</span> <span class="punct">)</span> <span class="punct">{</span> <span class="punct">...</span> <span class="punct">}</span></pre></div></div></div>
 	<p>The elements will be sorted based on their priorities, with lower priorities sorting closer to the instantiation block, and higher priorities sorting closer to the client.</p>
 	<h3>Making Custom Pipeline Elements Available</h3>
 	<p>You can make your custom pipeline elements available (so they can be referenced by symbol, instead of class name) by adding them to the <code>:pipeline_elements</code> service:</p>
-<pre>
-  reg.pipeline_elements[ :my_pipeline_element ] = MyPipelineElement
-  reg.register( :foo, :pipeline =&gt; [ :singleton, :my_pipeline_element ] ) { ... }
-</pre>
+	<div class='figure'>
+<span class='caption'>Publishing custom pipeline elements [ruby]</span>
+<div class='body'><table border='0' cellpadding='0' cellspacing='0'><tr><td class='lineno'>1<br />2<br /></td><td width='100%'><link rel='stylesheet' type='text/css' href='stylesheets/ruby.css' /><div class='ruby'><pre><span class="ident">reg</span><span class="punct">.</span><span class="ident">pipeline_elements</span><span class="punct">[</span> <span class="symbol">:my_pipeline_element</span> <span class="punct">]</span> <span class="punct">=</span> <span class="constant">MyPipelineElement</span>
+<span class="ident">reg</span><span class="punct">.</span><span class="ident">register</span><span class="punct">(</span> <span class="symbol">:foo</span><span class="punct">,</span> <span class="symbol">:pipeline</span> <span class="punct">=&gt;</span> <span class="punct">[</span> <span class="symbol">:singleton</span><span class="punct">,</span> <span class="symbol">:my_pipeline_element</span> <span class="punct">]</span> <span class="punct">)</span> <span class="punct">{</span> <span class="punct">...</span> <span class="punct">}</span></pre></div></td></tr></table></div></div>
    </div>
@@ -315,9 +346,11 @@
    <div class="section">
      <p>Specifying an entire pipeline for every service point can be tedious. For that reason, there are <em>service models</em>. A service model is a kind of template that names a pre-configured sequence of pipeline elements. Needle comes preconfigured with many service models.</p>
 	<h3>Standard Service Models:</h3>
-	<table style="border: 1px solid black;">
+	<table class="list">
 		<tr>
 			<th style="text-align:left;">Name</th>
 			<th style="text-align:left;">Pipeline</th>
@@ -407,27 +440,42 @@
 	<h3>Specifying a Service Model</h3>
 	<p>You specify the service model by passing the <code>:model</code> option when you register a service. (You must only specify <em>either</em> the model, <em>or</em> the pipeline, but not both.)</p>
-<pre>
-  reg.register( :foo, :model =&gt; :singleton_deferred ) {...}
-</pre>
+	<div class='figure'>
+<span class='caption'>Specifying a service model [ruby]</span>
+<div class='body'><link rel='stylesheet' type='text/css' href='stylesheets/ruby.css' /><div class='ruby'><pre><span class="ident">reg</span><span class="punct">.</span><span class="ident">register</span><span class="punct">(</span> <span class="symbol">:foo</span><span class="punct">,</span> <span class="symbol">:model</span> <span class="punct">=&gt;</span> <span class="symbol">:singleton_deferred</span> <span class="punct">)</span> <span class="punct">{...}</span></pre></div></div></div>
 	<h3>Defining New Models</h3>
 	<p>You can create your own service models by adding the corresponding pipelines to the <code>:service_models</code> service:</p>
-<pre>
-  reg.service_models[ :my_service_model ] = [ :singleton, :my_pipeline_element ]
-  reg.register( :foo, :model =&gt; :my_service_model ) {...}
-</pre>
+	<div class='figure'>
+<span class='caption'>Defining a custom model [ruby]</span>
+<div class='body'><table border='0' cellpadding='0' cellspacing='0'><tr><td class='lineno'>1<br />2<br /></td><td width='100%'><link rel='stylesheet' type='text/css' href='stylesheets/ruby.css' /><div class='ruby'><pre><span class="ident">reg</span><span class="punct">.</span><span class="ident">service_models</span><span class="punct">[</span> <span class="symbol">:my_service_model</span> <span class="punct">]</span> <span class="punct">=</span> <span class="punct">[</span> <span class="symbol">:singleton</span><span class="punct">,</span> <span class="symbol">:my_pipeline_element</span> <span class="punct">]</span>
+<span class="ident">reg</span><span class="punct">.</span><span class="ident">register</span><span class="punct">(</span> <span class="symbol">:foo</span><span class="punct">,</span> <span class="symbol">:model</span> <span class="punct">=&gt;</span> <span class="symbol">:my_service_model</span> <span class="punct">)</span> <span class="punct">{...}</span></pre></div></td></tr></table></div></div>
    </div>
+<div class="bottom"><div class="prevnext">
+    <a href="chapter-5.html">Previous (5. Interceptors)</a> |
+  <a href="index.html">Up</a>
+    | <a href="chapter-7.html">Next (7. Logging)</a>
+</div></div>
         </div>

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

@@ -1,7 +1,7 @@
 <html>
   <head>
     <title>Needle Manual :: Chapter 7: Logging</title>
-    <link type="text/css" rel="stylesheet" href="manual.css" />
+    <link type="text/css" rel="stylesheet" href="stylesheets/manual.css" />
   </head>
   <body>
@@ -14,8 +14,8 @@
           </div>
         </td><td valign='middle' align='right'>
           <div class="info">
-            Needle Version: <strong>1.2.0</strong><br />
-            Manual Last Updated: <strong>2004-11-18 15:36 GMT</strong>
+            Needle Version: <strong>1.2.1</strong><br />
+            Manual Last Updated: <strong>2005-07-27 05:49 UTC</strong>
           </div>
         </td></tr>
       </table>
@@ -208,7 +208,17 @@
         <div id="content">
-          <h1>7. Logging</h1>
+           <div class="top"><div class="prevnext">
+    <a href="chapter-6.html">Previous (6. Service Models)</a> |
+  <a href="index.html">Up</a>
+    | <a href="chapter-8.html">Next (8. Service Libraries)</a>
+</div></div>
+<h1>7. Logging</h1>
@@ -222,8 +232,10 @@
    <div class="section">
      <p>Logging is a pretty common activity in many applications. Because it is so common, Needle provides a powerful framework for logging messages in a consistent manner.</p>
 	<p>Needle&#8217;s logging framework is built on top of the standard Ruby <code>Logger</code> library. However, it extends that library to add additional functionality, including customizable message formats and a centralized location for obtaining logger instances.</p>
 	<p>This centralized location is the LogFactory.</p>
    </div>
@@ -240,43 +252,53 @@
      <p>The LogFactory is available as a service, so that any component that needs a logger instance can gain easy access to one. The factory&#8217;s service name is <code>:logs</code>.</p>
-<pre>
-  factory = reg.logs
-</pre>
+	<div class='figure'>
+<span class='caption'>Accessing the LogFactory service [ruby]</span>
+<div class='body'><link rel='stylesheet' type='text/css' href='stylesheets/ruby.css' /><div class='ruby'><pre><span class="ident">factory</span> <span class="punct">=</span> <span class="ident">reg</span><span class="punct">.</span><span class="ident">logs</span></pre></div></div></div>
 	<p>You obtain logger instances from the factory by passing a logger name to <code>#get</code>:</p>
-<pre>
-  logger = reg.logs.get "a logger name"
-</pre>
+	<div class='figure'>
+<span class='caption'>Getting a named logger instance [ruby]</span>
+<div class='body'><link rel='stylesheet' type='text/css' href='stylesheets/ruby.css' /><div class='ruby'><pre><span class="ident">logger</span> <span class="punct">=</span> <span class="ident">reg</span><span class="punct">.</span><span class="ident">logs</span><span class="punct">.</span><span class="ident">get</span> <span class="punct">&quot;</span><span class="string">a logger name</span><span class="punct">&quot;</span></pre></div></div></div>
 	<p>Subsequent calls to <code>#get</code> will return the same logger instance for the given logger name.</p>
 	<h3>Loggers for Services</h3>
 	<p>Typically, you&#8217;ll use this to assign a logger instance to a service when it is constructed. In that case, the name of the logger is the fully-qualified name of the service:</p>
-<pre>
-  reg.register( :foo ) do |c,p|
-    Foo.new( c.logs.get( p.fullname ) )
-  end
-</pre>
+	<div class='figure'>
+<span class='caption'>Getting a logger for a service [ruby]</span>
+<div class='body'><table border='0' cellpadding='0' cellspacing='0'><tr><td class='lineno'>1<br />2<br />3<br /></td><td width='100%'><link rel='stylesheet' type='text/css' href='stylesheets/ruby.css' /><div class='ruby'><pre><span class="ident">reg</span><span class="punct">.</span><span class="ident">register</span><span class="punct">(</span> <span class="symbol">:foo</span> <span class="punct">)</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">c</span><span class="punct">,</span><span class="ident">p</span><span class="punct">|</span>
+  <span class="constant">Foo</span><span class="punct">.</span><span class="ident">new</span><span class="punct">(</span> <span class="ident">c</span><span class="punct">.</span><span class="ident">logs</span><span class="punct">.</span><span class="ident">get</span><span class="punct">(</span> <span class="ident">p</span><span class="punct">.</span><span class="ident">fullname</span> <span class="punct">)</span> <span class="punct">)</span>
+<span class="keyword">end</span></pre></div></td></tr></table></div></div>
 	<p>As a convenience, if the value passed to <code>#get</code> responds to either <code>fullname</code> or <code>name</code>, the return value of that message will be used as the name. Thus, you can do the following:</p>
-<pre>
-  reg.register( :foo ) do |c,p|
-    Foo.new( c.logs.get( p ) )
-  end
-</pre>
+	<div class='figure'>
+<span class='caption'>Getting a logger for a service (simplified) [ruby]</span>
+<div class='body'><table border='0' cellpadding='0' cellspacing='0'><tr><td class='lineno'>1<br />2<br />3<br /></td><td width='100%'><link rel='stylesheet' type='text/css' href='stylesheets/ruby.css' /><div class='ruby'><pre><span class="ident">reg</span><span class="punct">.</span><span class="ident">register</span><span class="punct">(</span> <span class="symbol">:foo</span> <span class="punct">)</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">c</span><span class="punct">,</span><span class="ident">p</span><span class="punct">|</span>
+  <span class="constant">Foo</span><span class="punct">.</span><span class="ident">new</span><span class="punct">(</span> <span class="ident">c</span><span class="punct">.</span><span class="ident">logs</span><span class="punct">.</span><span class="ident">get</span><span class="punct">(</span> <span class="ident">p</span> <span class="punct">)</span> <span class="punct">)</span>
+<span class="keyword">end</span></pre></div></td></tr></table></div></div>
 	<p>As a further convenience, there is a <code>:log_for</code> service that is parameterized. Just pass the name of the log to retreive (or the service point instance) and it will return the log handle directly:</p>
-<pre>
-  reg.register( :foo ) do |c,p|
-    Foo.new( c.log_for( p ) )
-  end
-</pre>
+	<div class='figure'>
+<span class='caption'>Getting a logger for a service (simplified further) [ruby]</span>
+<div class='body'><table border='0' cellpadding='0' cellspacing='0'><tr><td class='lineno'>1<br />2<br />3<br /></td><td width='100%'><link rel='stylesheet' type='text/css' href='stylesheets/ruby.css' /><div class='ruby'><pre><span class="ident">reg</span><span class="punct">.</span><span class="ident">register</span><span class="punct">(</span> <span class="symbol">:foo</span> <span class="punct">)</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">c</span><span class="punct">,</span><span class="ident">p</span><span class="punct">|</span>
+  <span class="constant">Foo</span><span class="punct">.</span><span class="ident">new</span><span class="punct">(</span> <span class="ident">c</span><span class="punct">.</span><span class="ident">log_for</span><span class="punct">(</span> <span class="ident">p</span> <span class="punct">)</span> <span class="punct">)</span>
+<span class="keyword">end</span></pre></div></td></tr></table></div></div>
    </div>
@@ -291,6 +313,7 @@
    <div class="section">
      <p>You can configure the LogFactory when you create the registry by passing a hash as the <code>:logs</code> option to <code>Registry.new</code>. The hash may have the following properties:</p>
 	<table>
 		<tr>
 			<td style="vertical-align:top;"><code>:device</code></td>
@@ -332,29 +355,42 @@
 	<p>By default, the filename is &#8221;./needle.log&#8221;, and the roll_size is one megabyte. The default level is <code>:debug</code>. If you wanted to specify a different filename and default level of <code>:warn</code>, you could do:</p>
-<pre>
-  reg = Needle::Registry.new(
-    :logs =&gt; {
-      :filename =&gt; "./my-app.log",
-      :default_level =&gt; :warn }
-  )
-</pre>
+	<div class='figure'>
+<span class='caption'>Configuring the loggers [ruby]</span>
+<div class='body'><table border='0' cellpadding='0' cellspacing='0'><tr><td class='lineno'>1<br />2<br />3<br />4<br />5<br /></td><td width='100%'><link rel='stylesheet' type='text/css' href='stylesheets/ruby.css' /><div class='ruby'><pre><span class="ident">reg</span> <span class="punct">=</span> <span class="constant">Needle</span><span class="punct">::</span><span class="constant">Registry</span><span class="punct">.</span><span class="ident">new</span><span class="punct">(</span>
+  <span class="symbol">:logs</span> <span class="punct">=&gt;</span> <span class="punct">{</span>
+    <span class="symbol">:filename</span> <span class="punct">=&gt;</span> <span class="punct">&quot;</span><span class="string">./my-app.log</span><span class="punct">&quot;,</span>
+    <span class="symbol">:default_level</span> <span class="punct">=&gt;</span> <span class="symbol">:warn</span> <span class="punct">}</span>
+<span class="punct">)</span></pre></div></td></tr></table></div></div>
 	<p>Alternatively, you can easily put the logging configuration in a <span class="caps">YAML</span> file and read it in, like so:</p>
-<pre>
-  require 'yaml'
-  reg = Needle::Registry.new(
-    :logs =&gt; YAML.load( File.read( "log-conf.yml" ) )
-  )
-</pre>
+	<div class='figure'>
+<span class='caption'>Configuring the loggers from a YAML file [ruby]</span>
+<div class='body'><table border='0' cellpadding='0' cellspacing='0'><tr><td class='lineno'>1<br />2<br />3<br />4<br /></td><td width='100%'><link rel='stylesheet' type='text/css' href='stylesheets/ruby.css' /><div class='ruby'><pre><span class="ident">require</span> <span class="punct">'</span><span class="string">yaml</span><span class="punct">'</span>
+<span class="ident">reg</span> <span class="punct">=</span> <span class="constant">Needle</span><span class="punct">::</span><span class="constant">Registry</span><span class="punct">.</span><span class="ident">new</span><span class="punct">(</span>
+  <span class="symbol">:logs</span> <span class="punct">=&gt;</span> <span class="constant">YAML</span><span class="punct">.</span><span class="ident">load</span><span class="punct">(</span> <span class="constant">File</span><span class="punct">.</span><span class="ident">read</span><span class="punct">(</span> <span class="punct">&quot;</span><span class="string">log-conf.yml</span><span class="punct">&quot;</span> <span class="punct">)</span> <span class="punct">)</span>
+<span class="punct">)</span></pre></div></td></tr></table></div></div>
    </div>
+<div class="bottom"><div class="prevnext">
+    <a href="chapter-6.html">Previous (6. Service Models)</a> |
+  <a href="index.html">Up</a>
+    | <a href="chapter-8.html">Next (8. Service Libraries)</a>
+</div></div>
         </div>

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

@@ -1,7 +1,7 @@
 <html>
   <head>
     <title>Needle Manual :: Chapter 8: Service Libraries</title>
-    <link type="text/css" rel="stylesheet" href="manual.css" />
+    <link type="text/css" rel="stylesheet" href="stylesheets/manual.css" />
   </head>
   <body>
@@ -14,8 +14,8 @@
           </div>
         </td><td valign='middle' align='right'>
           <div class="info">
-            Needle Version: <strong>1.2.0</strong><br />
-            Manual Last Updated: <strong>2004-11-18 15:36 GMT</strong>
+            Needle Version: <strong>1.2.1</strong><br />
+            Manual Last Updated: <strong>2005-07-27 05:49 UTC</strong>
           </div>
         </td></tr>
       </table>
@@ -208,7 +208,17 @@
         <div id="content">
-          <h1>8. Service Libraries</h1>
+           <div class="top"><div class="prevnext">
+    <a href="chapter-7.html">Previous (7. Logging)</a> |
+  <a href="index.html">Up</a>
+    | <a href="chapter-9.html">Next (9. Customizing Needle)</a>
+</div></div>
+<h1>8. Service Libraries</h1>
@@ -222,6 +232,7 @@
    <div class="section">
      <p>Using Needle as it has been presented so far works fine when you are dealing with a single application, all self-encapsulated. When you start dealing with combining multiple libraries, each potentially written by a different author, into a single registry, things get a little more complicated.</p>
 	<p>Needle provides a way for service authors to share their services. All it requires is that authors centralize their service configuration.</p>
    </div>
@@ -237,33 +248,37 @@
    <div class="section">
      <p>This centralization is implemented by creating a module for each library you want to have services for. That module should then define a module function called (by default) <code>register_services</code>. This function should accept a single parameter&#8212;the Needle container that the services will be added to.</p>
 	<p>For example, if I had a library of cryptographic routines and I wanted to make them accessible as Needle services, I would create a module to contain the service definitions. Typically, this module will be defined in a file called &#8220;services.rb&#8221;, although you can certainly name it whatever you like.</p>
-<pre>
-  module Crypto
+	<div class='figure'>
+<span class='caption'>Needle-enabled library example [ruby]</span>
+<div class='body'><table border='0' cellpadding='0' cellspacing='0'><tr><td class='lineno'>1<br />2<br />3<br />4<br />5<br />6<br />7<br />8<br />9<br />10<br />11<br />12<br />13<br />14<br />15<br />16<br />17<br />18<br />19<br />20<br /></td><td width='100%'><link rel='stylesheet' type='text/css' href='stylesheets/ruby.css' /><div class='ruby'><pre><span class="keyword">module </span><span class="module">Crypto</span>
+  <span class="keyword">def </span><span class="method">register_services</span><span class="punct">(</span> <span class="ident">container</span> <span class="punct">)</span>
+    <span class="ident">container</span><span class="punct">.</span><span class="ident">namespace_define</span><span class="punct">(</span> <span class="symbol">:crypto</span> <span class="punct">)</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">b</span><span class="punct">|</span>
+      <span class="ident">b</span><span class="punct">.</span><span class="ident">prng</span> <span class="keyword">do</span>
+        <span class="ident">require</span> <span class="punct">'</span><span class="string">crypto/prng</span><span class="punct">'</span>
+        <span class="constant">PRNG</span><span class="punct">.</span><span class="ident">new</span>
+      <span class="keyword">end</span>
-    def register_services( container )
-      container.namespace_define( :crypto ) do |b|
-        b.prng do
-          require 'crypto/prng'
-          PRNG.new
-        end
+      <span class="ident">b</span><span class="punct">.</span><span class="ident">des</span> <span class="keyword">do</span>
+        <span class="ident">require</span> <span class="punct">'</span><span class="string">crypto/des</span><span class="punct">'</span>
+        <span class="constant">DES</span><span class="punct">.</span><span class="ident">new</span>
+      <span class="keyword">end</span>
-        b.des do
-          require 'crypto/des'
-          DES.new
-        end
+      <span class="punct">...</span>
+    <span class="keyword">end</span>
+  <span class="keyword">end</span>
+  <span class="ident">module_function</span> <span class="symbol">:register_services</span>
+<span class="keyword">end</span></pre></div></td></tr></table></div></div>
-        ...
-      end
-    end
-    module_function :register_services
-  end
-</pre>
 	<p>Notice that there are no explicit dependencies on Needle, only on the interfaces Needle publishes. Thus, third-parties can add service configuration modules to their libraries without introducing dependencies on Needle.</p>
 	<p>Once a service library has been created, it can then be accessed from another library or application that wishes to import those services.</p>
    </div>
@@ -280,38 +295,52 @@
      <p>Using the libraries is as simple as requiring the file that has the service definitions, and then invoking the <code>#register_services</code> module function:</p>
-<pre>
-  require 'needle'
+	<div class='figure'>
+<span class='caption'>Example of using a Needle-enabled library [ruby]</span>
+<div class='body'><table border='0' cellpadding='0' cellspacing='0'><tr><td class='lineno'>1<br />2<br />3<br />4<br />5<br />6<br />7<br />8<br />9<br />10<br />11<br /></td><td width='100%'><link rel='stylesheet' type='text/css' href='stylesheets/ruby.css' /><div class='ruby'><pre><span class="ident">require</span> <span class="punct">'</span><span class="string">needle</span><span class="punct">'</span>
-  reg = Needle::Registry.new
-  reg.define do |b|
-    b.foo { Foo.new }
+<span class="ident">reg</span> <span class="punct">=</span> <span class="constant">Needle</span><span class="punct">::</span><span class="constant">Registry</span><span class="punct">.</span><span class="ident">new</span>
+<span class="ident">reg</span><span class="punct">.</span><span class="ident">define</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">b</span><span class="punct">|</span>
+  <span class="ident">b</span><span class="punct">.</span><span class="ident">foo</span> <span class="punct">{</span> <span class="constant">Foo</span><span class="punct">.</span><span class="ident">new</span> <span class="punct">}</span>
+  <span class="ident">require</span> <span class="punct">'</span><span class="string">crypto/services</span><span class="punct">'</span>
+  <span class="constant">Crypto</span><span class="punct">.</span><span class="ident">register_services</span><span class="punct">(</span> <span class="ident">reg</span> <span class="punct">)</span>
+<span class="keyword">end</span>
+<span class="ident">prng</span> <span class="punct">=</span> <span class="ident">reg</span><span class="punct">.</span><span class="ident">crypto</span><span class="punct">.</span><span class="ident">prng</span></pre></div></td></tr></table></div></div>
-    require 'crypto/services'
-    Crypto.register_services( reg )
-  end
-  prng = reg.crypto.prng
-</pre>
 	<p>To make this easier, the Container class has a convenience method named <code>#require</code>:</p>
-<pre>
-  require 'needle'
+	<div class='figure'>
+<span class='caption'>Example of using Container#require [ruby]</span>
+<div class='body'><table border='0' cellpadding='0' cellspacing='0'><tr><td class='lineno'>1<br />2<br />3<br />4<br />5<br />6<br />7<br />8<br />9<br /></td><td width='100%'><link rel='stylesheet' type='text/css' href='stylesheets/ruby.css' /><div class='ruby'><pre><span class="ident">require</span> <span class="punct">'</span><span class="string">needle</span><span class="punct">'</span>
+<span class="ident">reg</span> <span class="punct">=</span> <span class="constant">Needle</span><span class="punct">::</span><span class="constant">Registry</span><span class="punct">.</span><span class="ident">new</span>
+<span class="ident">reg</span><span class="punct">.</span><span class="ident">define</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">b</span><span class="punct">|</span>
+  <span class="ident">b</span><span class="punct">.</span><span class="ident">foo</span> <span class="punct">{</span> <span class="constant">Foo</span><span class="punct">.</span><span class="ident">new</span> <span class="punct">}</span>
+  <span class="ident">b</span><span class="punct">.</span><span class="ident">require</span> <span class="punct">'</span><span class="string">crypto/services</span><span class="punct">',</span> <span class="punct">&quot;</span><span class="string">Crypto</span><span class="punct">&quot;</span>
+<span class="keyword">end</span>
+<span class="ident">prng</span> <span class="punct">=</span> <span class="ident">reg</span><span class="punct">.</span><span class="ident">crypto</span><span class="punct">.</span><span class="ident">prng</span></pre></div></td></tr></table></div></div>
-  reg = Needle::Registry.new
-  reg.define do |b|
-    b.foo { Foo.new }
-    b.require 'crypto/services', "Crypto"
-  end
-  prng = reg.crypto.prng
-</pre>
 	<p>The <code>Container#require</code> method will require the file, and then look for a <code>#register_services</code> method of the named module. It will execute that method, passing the container as an argument.</p>
    </div>
+<div class="bottom"><div class="prevnext">
+    <a href="chapter-7.html">Previous (7. Logging)</a> |
+  <a href="index.html">Up</a>
+    | <a href="chapter-9.html">Next (9. Customizing Needle)</a>
+</div></div>
         </div>