needle 1.1.0 → 1.2.0

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

@@ -14,8 +14,8 @@
           </div>
         </td><td valign='middle' align='right'>
           <div class="info">
-            Needle Version: <strong>1.1.0</strong><br />
-            Manual Last Updated: <strong>2004-11-11 17:31 GMT</strong>
+            Needle Version: <strong>1.2.0</strong><br />
+            Manual Last Updated: <strong>2004-11-18 15:36 GMT</strong>
           </div>
         </td></tr>
       </table>
@@ -220,8 +220,7 @@
    
 
    <div class="section">
-     <p>Needle is a dependency injection (also, inversion of control) container for <a href="http://www.ruby-lang.org">Ruby</a>.<br />
-</p>
+     <p>Needle is a dependency injection (also, inversion of control) container for <a href="http://www.ruby-lang.org">Ruby</a>.</p>
    </div>
 
 
@@ -239,7 +238,6 @@
 	<p>But what, <em>specifically</em>, can Needle do for you?</p>
 
 	<p>Try these on for size:</p>
-
 	<ul>
 	<li><a href="#logexec">Log Method Execution</a></li>
 		<li><a href="#refsvc">Reference Another Service</a></li>
@@ -255,6 +253,7 @@
 
 	<p>Consider the following code, demonstrating how this would be done without Needle:</p>
 
+
 <pre>
   def foo( arg1, arg2 )
     @log.debug( "in foo with #{arg1} and #{arg2}" ) if @log.debug?
@@ -267,31 +266,31 @@
     raise
   end
 </pre>
-
 	<p>Now, multiply that by the number of methods in your class&#8230; the logging messages quickly overpower the rest of the code, and detract from the flow of your program. This makes your program harder to debug, test, and maintain.</p>
 
 	<p>Now, consider the same method using Needle&#8217;s integrated logging framework&#8230;</p>
 
+
 <pre>
   def foo( arg1, arg2 )
     ...
     return the_result_of_the_method
   end
 </pre>
-
 	<p>Then, when you define the service that you want to add the logging to:</p>
 
+
 <pre>
   registry.register( :service_name_here ) { |reg| ... }
   registry.intercept( :service_name_here ).with! { logging_interceptor }
 </pre>
-
 	<p>That&#8217;s right. There&#8217;s no explicit logging code in there. Instead, you just tell Needle that the methods of the class should be logged, and away it goes. This has the added benefit of allowing your objects to be unit tested, without spewing log messages everywhere.</p>
 
 	<h3>Reference Another Service <a name="#refsvc"></a></h3>
 
 	<p>Invariably in a large application services will reference other services. This is typically accomplished through something like this:</p>
 
+
 <pre>
   class Component
     ...
@@ -306,11 +305,11 @@
     ...
   end
 </pre>
-
 	<p>Whether the lookup is done lazily, as shown above, or when the class is first instantiated is irrelevant. The point is that you either have to implement a bunch of code to look up a service based on some criteria, or you hard code the class of the service (which creates tight coupling and makes things like unit testing harder).</p>
 
 	<p>With Needle, you just declare a setter for the service, and then tell Needle that the class depends on the other service:</p>
 
+
 <pre>
   class Component
     attr_writer :service
@@ -327,7 +326,6 @@
     c
   end
 </pre>
-
 	<p>Then, when your service is instantiated, Needle will automatically look for and instantiate the dependencies for you. This makes for cleaner code, and looser coupling between services.</p>
 
 	<h3>Unit Testing <a name="#unittest"></a></h3>
@@ -338,15 +336,16 @@
 
 	<p>Consider this tightly coupled example:</p>
 
+
 <pre>
   def foo( args )
     @some_dependency ||= MyNewDependency.new
     @some_dependency.do_something(args)
   end
 </pre>
-
 	<p>It is impossible to test the method <code>#foo</code> without also testing the MyNewDependency class. However, if the <code>@some_dependency</code> object is made a property that is set externally, you can replace it at test time with a blank:</p>
 
+
 <pre>
   attr_writer :some_dependency
 
@@ -354,9 +353,9 @@
     @some_dependency.do_something( args )
   end
 </pre>
-
 	<p>The unit test would become something like this:</p>
 
+
 <pre>
   def test_foo
     @obj.some_dependecy = MyMockDependency.new
@@ -364,7 +363,6 @@
     assert @obj.is_in_some_state
   end
 </pre>
-
 	<h3>Lifecycle Management <a name="#lifecycle"></a></h3>
 
 	<p>Singleton objects are a fact of life in complex systems. The singleton design pattern is powerful and useful. However, using the Singleton mixin, or declaring methods at the class level, can make your code difficult to unit test since the state of such objects cannot be easily reset.</p>
@@ -389,14 +387,14 @@
 
    <div class="section">
      <p>Needle is not the only fish in the dependency-injection pond, even when it comes to Ruby. Other containers at your disposal include:</p>
-
 	<ul>
 	<li><a href="http://copland.rubyforge.org">Copland</a>. Copland aims to be an &#8220;application framework&#8221;, taking something of a heavy-weight approach to DI. In so doing, it provides functionality that Needle does not, but at the cost of performance. It also uses external (YAML) configuration files. It is inspired by a Java framework (<a href="http://jakarta.apache.org/hivemind">HiveMind</a>), and so has a vaguely Java-ish flavor to it.</li>
 		<li><a href="http://www.picocontainer.org/Rico">Rico</a>. Rico is another project inspired by a Java project (<a href="http://www.picocontainer.org">PicoContainer</a>). It is very lean, and appears to be experimental.</li>
 		<li><a href="http://sourceforge.jp/projects/nihohi/">Tudura</a>. I do not have any information on this project, as the information is all in Japanese. If someone with more information about Tudura would like to step forward, I&#8217;d be happy to post a summary here.</li>
+		<li><a href="http://redshift.sourceforge.net/mindi/">MinDI</a> is a recent contender that takes a very novel approach to dependency injection. Instead of instantiating a container and adding services to it, you declare a class, mixin a DI module, and add services to the class as methods, thereby making the class the container.</li>
 	</ul>
 
-	<p>There is, at the time of this writing, at least one other project on RubyForge devoted to DI, although it has no public releases yet.</p>
+	<p>There is, at the time of this writing, at least one other project on RubyForge devoted to <span class="caps">DI </span>(<a href="http://rubyforge.org/projects/pith">Pith</a>), although it has no public releases yet.</p>
 
 	<p>So, which one should you choose? It comes down to an issue of personal preference, mostly, but also one of what you are wanting to accomplish. Needle excels at providing an unobtrusive, light-weight container for managing your dependencies. The cost of it being light-weight is that there is functionality it does not provide, which other containers may. If you really need that missing functionality, you are required to either implement it yourself, or select a different container.</p>
 
@@ -417,8 +415,7 @@
 
 	<p>This manual (in any form, be it source or otherwise) and the scripts and templates used to generate it, are all distributed under the <a href="http://creativecommons.org">Creative Commons</a> <a href="http://creativecommons.org/licenses/by-sa/2.0">Attribution-ShareAlike</a> license.</p>
 
-	<p>If you desire permission to use either Needle or the manual in a manner incompatible with these licenses, please contact the copyright holder (<a href="mailto:jgb3@email.byu.edu">Jamis Buck</a>) in order to negotiate a more compatible license.<br />
-</p>
+	<p>If you desire permission to use either Needle or the manual in a manner incompatible with these licenses, please contact the copyright holder (<a href="mailto:jgb3@email.byu.edu">Jamis Buck</a>) in order to negotiate a more compatible license.</p>
    </div>
 
 
@@ -431,8 +428,7 @@
    
 
    <div class="section">
-     <p>Mailing lists, bug trackers, feature requests, and public forums are available (courtesy of <a href="http://rubyforge.org">RubyForge</a>) at Needle&#8217;s RubyForge project page. Just direct your browser to <a href="http://rubyforge.org/projects/needle">http://rubyforge.org/projects/needle</a>.<br />
-</p>
+     <p>Mailing lists, bug trackers, feature requests, and public forums are available (courtesy of <a href="http://rubyforge.org">RubyForge</a>) at Needle&#8217;s RubyForge project page. Just direct your browser to <a href="http://rubyforge.org/projects/needle">http://rubyforge.org/projects/needle</a>.</p>
    </div>
 
 

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

@@ -14,8 +14,8 @@
           </div>
         </td><td valign='middle' align='right'>
           <div class="info">
-            Needle Version: <strong>1.1.0</strong><br />
-            Manual Last Updated: <strong>2004-11-11 17:31 GMT</strong>
+            Needle Version: <strong>1.2.0</strong><br />
+            Manual Last Updated: <strong>2004-11-18 15:36 GMT</strong>
           </div>
         </td></tr>
       </table>
@@ -222,8 +222,7 @@
    <div class="section">
      <p>The registry is at the heart of any dependency-injected application or library. All services are registered with the registry, so that when an application needs an instance of a particular service, it may obtain that service reference by querying the registry.</p>
 
-	<p>In order to use Needle, you only really <em>need</em> to understand how to create and manipulate registry objects.<br />
-</p>
+	<p>In order to use Needle, you only really <em>need</em> to understand how to create and manipulate registry objects.</p>
    </div>
 
 
@@ -238,44 +237,43 @@
    <div class="section">
      <p>Creating a registry is as simple as calling <code>Needle::Registry.new</code>. This will give you a new registry object, bootstrapped to contain a few general services.</p>
 
+
 <pre>
   require 'needle'
 
   registry = Needle::Registry.new
 </pre>
-
 	<p>Once you have the reference to the registry, you can register services with it, create new namespaces in it, and so forth.</p>
 
 	<p>Alternatively, you can pass a block to <code>#new</code>:</p>
 
+
 <pre>
   registry = Needle::Registry.new do |r|
     ...
   end
 </pre>
-
 	<p>The parameter to the block will be a reference to the registry. This allows you to register services with the registry as soon as it is created.</p>
 
 	<p>Another convenience method is <code>#define!</code>:</p>
 
+
 <pre>
   registry = Needle::Registry.define! do
     ...
   end
 </pre>
-
 	<p>This block accepts no parameters, and evaluates the block as if it were passed to <code>Registry#define!</code> (see below).</p>
 
 	<p>There can be problems with using <code>define!</code>, however, since it uses <code>instance_eval</code> to evaluate the block within the context of another object. If you find yourself running into scoping issues, you might want to consider using <code>#define</code>:</p>
 
+
 <pre>
   registry = Needle::Registry.define do |b|
     ...
   end
 </pre>
-
-	<p>This block accepts a single parameter&#8212;a &#8220;builder&#8221; object to aid in registering services&#8212;and evaluates the block as if it were passed to <code>Registry#define</code> (see below).<br />
-</p>
+	<p>This block accepts a single parameter&#8212;a &#8220;builder&#8221; object to aid in registering services&#8212;and evaluates the block as if it were passed to <code>Registry#define</code> (see below).</p>
    </div>
 
 
@@ -290,14 +288,15 @@
    <div class="section">
      <p>Registering services with a Needle registry is very straightforward. The simplest way to do it is:</p>
 
+
 <pre>
   registry.register( :foo ) { Bar.new }
 </pre>
-
 	<p>The above will register a new service with the registry, naming it <code>:foo</code>. When <code>:foo</code> is requested from the registry, a new instance of <code>Bar</code> will be instantiated and returned.</p>
 
 	<p>You get services from the registry in either of two ways:</p>
 
+
 <pre>
   # Treating the registry as a Hash
   svc = registry[:foo]
@@ -305,13 +304,13 @@
   # Treating the service as a property of the registry
   svc = registry.foo
 </pre>
-
 	<h3>Convenience Methods</h3>
 
 	<p>Because you will often need to register many services with a registry at once, two convenience methods have been provided to make this use case lean and mean.</p>
 
 	<p>The first is <code>define</code>. Just pass a block to define that accepts one parameter. This parameter will be a &#8220;builder&#8221; object that allows you to define services just by sending them as messages to the builder:</p>
 
+
 <pre>
   registry.define do |b|
     b.foo { Bar.new }
@@ -319,9 +318,9 @@
     ...
   end
 </pre>
-
 	<p>Alternative, you can call <code>define!</code>, passing a block that accepts no parameters. This block will be evaluated in the &#8220;builder&#8221; object&#8217;s context, with any unrecognized method call being interpreted as a new service registration of that name:</p>
 
+
 <pre>
   registry.define! do
     foo { Bar.new }
@@ -329,22 +328,53 @@
     ...
   end
 </pre>
-
 	<p>Both of the above will register two new services with the registry, <code>:foo</code> and <code>:bar</code>.</p>
 
 	<h3>Default Lifecycle</h3>
 
 	<p>By default, a service is only instantiated once per registry. This means that (using the above example) if the service <code>:foo</code> were queried twice, the registry would return the same object for both queries:</p>
 
+
 <pre>
   svc1 = registry.foo
   svc2 = registry.foo
 
   p svc1.object_id == svc2.object_id #=&gt; true
 </pre>
+	<p>You can change this behavior, with <em>service models</em>. See the chapter on Service Models for more information.</p>
+
+	<h3>Parameterized Services</h3>
+
+	<p>Needle also supports <em>parameterized services</em>. These are services that, when requested, require contextual information to be passed as a parameter so that the service can be correctly initialized.</p>
+
+	<p>Consider the following example, in which some hypothetical <code>Printer</code> class represents any of a number of printers, based on a parameter given to its constructor.</p>
+
+
+<pre>
+  registry.register( :printer, :model =&gt; :multiton ) do |c,p,name|
+    Printer.new( c.log_for( p ), name )
+  end
+
+  mono  = registry.printer( :monochrome )
+  color = registry.printer( :color )
+</pre>
+	<p>There are a few things to note about the above example:</p>
+	<ol>
+	<li>The <code>:multiton</code> model is explicitly requested. This is necessary because the default service model (<code>:singleton</code>) does not allow parameterized services. Most of the time, you&#8217;ll use the multiton service model with parameterized services, but you don&#8217;t have to. You could also use any of the prototype models as well.
+</li>
+		<li>The constructor block for the <code>:printer</code> service takes three parameters, <code>c</code>, <code>p</code>, and <code>name</code>. The first two parameters, <code>c</code> and <code>p</code>, represent the container and the service point, respectively. Any parameters after those two are the contextual parameters given when the service is requested. In this case, there is only one contextual parameter: the name of the printer.
+</li>
+		<li>Notice the first parameter to the Printer constructor: <code>c.log_for(p)</code>. This is itself invoking a parameterized service, named <code>:log_for</code>, and passing <code>p</code> as the contextual information. This will return a new logger handle for the service point <code>p</code> (i.e., the current service point).
+</li>
+		<li>See how the printer service is requested on the last two lines. In this case, the <code>#printer</code> message is sent to the registry with a single parameter. You can also request the service in two other ways:</li>
+	</ol>
 
-	<p>You can change this behavior, with <em>service models</em>. See the chapter on Service Models for more information.<br />
-</p>
+
+<pre>
+  dot_matrix = registry[ :printer, :dot_matrix ]
+  ink_jet    = registry.get( :printer, :ink_jet )
+</pre>
+	<p>Choose the style that works best for you.</p>
    </div>
 
 
@@ -358,7 +388,6 @@
 
    <div class="section">
      <p>Namespaces allow you to organize your services. The feature has many different applications, including:</p>
-
 	<ol>
 	<li>Third-parties may distribute Needle-enabled libraries without worrying about their choice of service names conflicting with the service names of their clients.</li>
 		<li>Developers may organize complex applications into modules, and the service definitions may be stored in the registry to reflect that organization.</li>
@@ -367,53 +396,53 @@
 
 	<p>Creating a namespace is as easy as invoking the <code>#namespace</code> method of the registry (or of another namespace):</p>
 
+
 <pre>
   registry.namespace :stuff
 </pre>
-
 	<p>This would create a new namespace in the registry called <code>:stuff</code>. The application may then proceed to register services inside that namespace:</p>
 
+
 <pre>
   registry.stuff.register( :foo ) { Bar.new }
   ...
   svc = registry.stuff.foo
 </pre>
-
 	<p>Here&#8217;s a tip: <em>namespaces are just a special kind of service.</em> This means that you can access namespaces in the same ways that you can access services:</p>
 
+
 <pre>
   svc = registry[:stuff][:foo]
 </pre>
-
 	<h3>Convenience Methods</h3>
 
 	<p>Because it is often the case that you will be creating a namespace and then immediately registering services on it, you can pass a block to <code>namespace</code>. The block will receive a reference to the new namespace:</p>
 
+
 <pre>
   registry.namespace :stuff do |spc|
     spc.register( :foo ) { Bar.new }
     ...
   end
 </pre>
-
 	<p>If you prefer the <code>define</code> approach to registering services, you may like <code>namespace_define</code>, which creates the new namespace and immediately calls <code>define</code> on it:</p>
 
+
 <pre>
   registry.namespace_define :stuff do |b|
     b.foo { Bar.new }
     ...
   end
 </pre>
-
 	<p>And, to mirror the <code>namespace_define</code> method, there is also a <code>namespace_define!</code> method. This method creates a new namespace and then does a <code>define!</code> call on that namespace.</p>
 
+
 <pre>
   registry.namespace_define! :stuff do
     foo { Bar.new }
     ...
   end
 </pre>
-
 	<p>The above code would create a new namespace called <code>:stuff</code> in the registry, and would then proceed to register a service called <code>:foo</code> in the new namespace.</p>
    </div>
 

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

@@ -14,8 +14,8 @@
           </div>
         </td><td valign='middle' align='right'>
           <div class="info">
-            Needle Version: <strong>1.1.0</strong><br />
-            Manual Last Updated: <strong>2004-11-11 17:31 GMT</strong>
+            Needle Version: <strong>1.2.0</strong><br />
+            Manual Last Updated: <strong>2004-11-18 15:36 GMT</strong>
           </div>
         </td></tr>
       </table>
@@ -223,7 +223,6 @@
      <p>The <em>service locator</em> design pattern can be considered a subset of dependency injection. Because it is simpler, it is as good of a place to start teaching DI as any.</p>
 
 	<p>To demonstrate both techniques, we&#8217;ll pretend we&#8217;re going to write an online forum application. To start, let&#8217;s come up with a rough design by cataloging the components we&#8217;ll need.</p>
-
 	<ul>
 	<li><code>Logger</code>. This will be used to write messages to a file.</li>
 		<li><code>Authenticator</code>. This will be used to validate whether a user is who they say they are.</li>
@@ -236,7 +235,6 @@
 	<p>(Of course, a <em>real</em> online forum application would be significantly more complex, but the above components will do for our purposes.)</p>
 
 	<p>The dependencies between these components are:</p>
-
 	<ul>
 	<li><code>Authenticator</code> <em>has</em> <code>Database</code> (for querying user authentication information) and <code>Logger</code></li>
 		<li><code>Database</code> <em>has</em> <code>Logger</code> (for indicating database accesses and query times)</li>
@@ -257,6 +255,7 @@
    <div class="section">
      <p>A conventional architecture will have each component instantiate its own dependencies. For example, the <code>Application</code> would do something like this:</p>
 
+
 <pre>
   class Application
     def initialize
@@ -268,9 +267,9 @@
     end
   end
 </pre>
-
 	<p>However, the above is already flawed, because the <code>Authenticator</code> and the <code>Session</code> both need access to the <code>Database</code>, so you really need to make sure you instantiate things in the right order and pass them as parameters to the constructor of each object that needs them, like so:</p>
 
+
 <pre>
   class Application
     def initialize
@@ -282,9 +281,7 @@
     end
   end
 </pre>
-
-	<p>The problem with this is that if you later decide that <code>View</code> needs to access the database, you need to rearrange the order of how things are instantiated in the <code>Application</code> constructor.<br />
-</p>
+	<p>The problem with this is that if you later decide that <code>View</code> needs to access the database, you need to rearrange the order of how things are instantiated in the <code>Application</code> constructor.</p>
    </div>
 
 
@@ -299,6 +296,7 @@
    <div class="section">
      <p>The <em>service locator</em> pattern makes things a <em>little</em> easier. Instead of instantiating everything in the constructor of the <code>Application</code>, you can create a factory method somewhere that returns the new <code>Application</code> instance. Then, inside of this factory method, you assign each new object to collection, and pass that collection to each constructor.</p>
 
+
 <pre>
   require 'needle'
 
@@ -334,7 +332,6 @@
 
   ...
 </pre>
-
 	<p>This has the benefit of allowing each object to construct itself <em>� la carte</em> from the objects in the locator. Also, each object no longer cares what class implements each service&#8212;it only cares that each object implements the methods it will attempt to invoke on that object.</p>
 
 	<p>Also, because Needle defers the instantiation of each service until the service is actually requested, we can actually register each item with the locator in any arbitrary order. All that is happening is the block is associated with the symbol, so that when the service is requested, the corresponding block is invoked. What is more, by default each service is then cached, so that it is only instantiated once.</p>
@@ -343,6 +340,7 @@
 
 	<p>In the interest of brevity, the <code>create_application</code> could have been written like this, using a &#8220;builder&#8221; object (called <code>b</code> in the example below) to help register the services:</p>
 
+
 <pre>
   def create_application
     locator = Needle::Registry.define do |b|