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

needle 1.2.0 → 1.2.1

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>