needle 1.1.0 → 1.2.0

data/doc/manual-html/chapter-9.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>
@@ -226,6 +226,7 @@
 
 	<p>Here&#8217;s a contrived example. Suppose you want each namespace to keep track of the precise time that it was created.</p>
 
+
 <pre>
   class TimeTrackerNamespace &lt; Needle::Container
     attr_reader :birth_date
@@ -242,9 +243,7 @@
   reg.namespace :hello
   p reg.hello.birth_date
 </pre>
-
-	<p>In general, you&#8217;ll be better off having your custom implementation extend <code>Needle::Container</code>, although the only <em>real</em> requirement is that your implementation publish the same interface as the default namespace implementation.<br />
-</p>
+	<p>In general, you&#8217;ll be better off having your custom implementation extend <code>Needle::Container</code>, although the only <em>real</em> requirement is that your implementation publish the same interface as the default namespace implementation.</p>
    </div>
 
 
@@ -261,12 +260,13 @@
 
 	<p>It is this wrapper object that allows interceptor definitions to be done using method chaining:</p>
 
+
 <pre>
   reg.intercept( :foo ).with { ... }.with_options(...)
 </pre>
-
 	<p>If you wish to add custom, domain-specific functionality to the interceptor wrapper, you can register your own implementation of the <code>:interceptor_impl_factory</code>. Consider the following contrived example, where an &#8220;only_if&#8221; clause is given to determine when the interceptor should be invoked.</p>
 
+
 <pre>
   class OnlyIfInterceptor &lt; Needle::Interceptor
     def only_if( &#38;block )
@@ -313,6 +313,7 @@
 
 	<p>Consider the following contrived example, where you want to provide a convenient way to register services of type Hash.</p>
 
+
 <pre>
   class MyDefinitionContext &lt; Needle::DefinitionContext
     def register_hash( name, opts={} )

data/doc/manual-html/index.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>
@@ -234,7 +234,9 @@
   <table border='0' cellpadding='0' cellspacing='0' align='center'><tr><td>
     <ul>
       
-        <li>Added chapter on "Customizing Needle"</li>
+        <li>Described parameterized services</li>
+      
+        <li>Added multiton service models to list of available models</li>
       
     </ul>
   </table>

data/doc/manual/manual.yml

@@ -23,7 +23,8 @@ product: !^product
     - Needle Wiki: http://needle.rubyforge.org/wiki/wiki.pl
 
 recent_updates:
-  - Added chapter on "Customizing Needle"
+  - Described parameterized services
+  - Added multiton service models to list of available models
 
 chapters:
 

data/doc/manual/parts/01_alternatives.txt

@@ -3,8 +3,9 @@ Needle is not the only fish in the dependency-injection pond, even when it comes
 * "Copland":http://copland.rubyforge.org. Copland aims to be an "application framework", 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 ("HiveMind":http://jakarta.apache.org/hivemind), and so has a vaguely Java-ish flavor to it.
 * "Rico":http://www.picocontainer.org/Rico. Rico is another project inspired by a Java project ("PicoContainer":http://www.picocontainer.org). It is very lean, and appears to be experimental.
 * "Tudura":http://sourceforge.jp/projects/nihohi/. 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'd be happy to post a summary here.
+* "MinDI":http://redshift.sourceforge.net/mindi/ 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.
 
-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.
+There is, at the time of this writing, at least one other project on RubyForge devoted to DI ("Pith":http://rubyforge.org/projects/pith), although it has no public releases yet.
 
 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.
 

data/doc/manual/parts/02_services.txt

@@ -54,3 +54,36 @@ By default, a service is only instantiated once per registry. This means that (u
 </pre>
 
 You can change this behavior, with _service models_. See the chapter on Service Models for more information.
+
+h3. Parameterized Services
+
+Needle also supports _parameterized services_. These are services that, when requested, require contextual information to be passed as a parameter so that the service can be correctly initialized.
+
+Consider the following example, in which some hypothetical @Printer@ class represents any of a number of printers, based on a parameter given to its constructor.
+
+<pre>
+  registry.register( :printer, :model => :multiton ) do |c,p,name|
+    Printer.new( c.log_for( p ), name )
+  end
+
+  mono  = registry.printer( :monochrome )
+  color = registry.printer( :color )
+</pre>
+
+There are a few things to note about the above example:
+
+# The @:multiton@ model is explicitly requested. This is necessary because the default service model (@:singleton@) does not allow parameterized services. Most of the time, you'll use the multiton service model with parameterized services, but you don't have to. You could also use any of the prototype models as well.
+
+# The constructor block for the @:printer@ service takes three parameters, @c@, @p@, and @name@. The first two parameters, @c@ and @p@, 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.
+
+# Notice the first parameter to the Printer constructor: @c.log_for(p)@. This is itself invoking a parameterized service, named @:log_for@, and passing @p@ as the contextual information. This will return a new logger handle for the service point @p@ (i.e., the current service point).
+
+# See how the printer service is requested on the last two lines. In this case, the @#printer@ message is sent to the registry with a single parameter. You can also request the service in two other ways:
+
+<pre>
+  dot_matrix = registry[ :printer, :dot_matrix ]
+  ink_jet    = registry.get( :printer, :ink_jet )
+</pre>
+
+Choose the style that works best for you.
+

data/doc/manual/parts/logging_logfactory.txt

@@ -29,3 +29,12 @@ As a convenience, if the value passed to @#get@ responds to either @fullname@ or
     Foo.new( c.logs.get( p ) )
   end
 </pre>
+
+As a further convenience, there is a @:log_for@ 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:
+
+<pre>
+  reg.register( :foo ) do |c,p|
+    Foo.new( c.log_for( p ) )
+  end
+</pre>
+

data/doc/manual/parts/models_models.txt

@@ -4,6 +4,10 @@ h3. Standard Service Models:
 
 table{border: 1px solid black}.
 |_<. Name|_<. Pipeline|_<. Effect|
+|^. @:multiton@|^. @:multiton@|The returned value will be unique for each unique parameter set given to the service.|
+|^. @:multiton_deferred@|^. @:multiton@, @:deferred@|As @:multiton@, but a proxy is returned, deferring the instantiation of the service itself until a method is invoked on it.|
+|^. @:multiton_initialize@|^. @:multiton@, @:initialize@|As @:multiton@, but invoke an initialization method on every service instance as soon as they are created.|
+|^. @:multiton_deferred_initialize@|^. @:multiton@, @:deferred@, @:initialize@|As @:multiton@, but a proxy is returned, deferring the instantiation of the service itself until a method is invoked on it. When the service is instantiated, an initialization method will be invoked on it.|
 |^. @:prototype@|^. (empty)|Immediately instantiate the service, at every request.|
 |^. @:prorotype_deferred@|^. @:deferred@|Return a proxy, that will instantiate the service the first time a method is invoked on the proxy. A new proxy instance will be returned for each request.|
 |^. @:prototype_initialize@|^. @:initialize@|Immediately instantiate the service, and invoke an initialization method, at every request.|

data/doc/manual/parts/models_pipelines.txt

@@ -9,6 +9,7 @@ There are five standard pipeline elements available in Needle (although you may
 * @deferred@: 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).
 * @initialize@: this will invoke a method on the resulting service (defaults to @initialize_service@, though it can be changed). It is used for doing final initialization of services (for services that need it).
 * @interceptor@: this element is used to implement the proxy that wraps the interceptors around the service. It is only attached to the pipeline when an interceptor is attached to a service.
+* @multiton@: this element enforces a multiton guard on the service. This means that the service will only be instantiated once for each unique set of parameters given to the service.
 * @singleton@: this is a multiplicity guard that ensures a service is instantiated only once per process.
 * @threaded@: this is like the @singleton@ element, but it ensures that a service is instantiated no more than once _per thread_.
 

data/lib/needle/container.rb

@@ -36,7 +36,15 @@ module Needle
     # The name of this container. May be +nil+.
     attr_reader :name
 
-    # Create a new empty container with the given parent and name.
+    # A hash of default options to use when registering services. These
+    # defaults also apply to namespaces, so when specifying a new default
+    # service model (for instance) there may be unexpected side-effects with
+    # the namespaces that are created.
+    attr_reader :defaults
+
+    # Create a new empty container with the given parent and name. If a parent
+    # is given, this container will inherit the defaults of the parent at the
+    # time the container was created.
     def initialize( parent=nil, name=nil )
       @root = nil
       @builder = nil
@@ -44,6 +52,8 @@ module Needle
       @name = name
       @parent = parent
       @service_points = Hash.new
+
+      @defaults = ( parent.nil? ? Hash.new : parent.defaults.dup )
     end
 
     # Returns the root of the current hierarchy. If the container is the
@@ -55,11 +65,19 @@ module Needle
       @root = parent.root
     end
 
+    # Returns +true+ if this container either is the given container or is
+    # descended from the given container, and +false+ otherwise.
+    def descended_from?( container )
+      return true if self == container
+      return false unless parent
+      parent.descended_from? container
+    end
+
     # Return the fully qualified name of this container, which is the
     # container's name and all parent's names up to the root container,
     # catenated together with dot characters, i.e., "one.two.three".
     def fullname
-      parent_name = ( @parent ? @parent.fullname : nil )
+      parent_name = ( parent ? parent.fullname : nil )
       return @name.to_s unless parent_name
       "#{parent_name}.#{@name}"
     end
@@ -120,7 +138,7 @@ module Needle
 
       name = name.to_s.intern unless name.is_a?( Symbol )
       @service_points[ name ] =
-        ServicePoint.new( self, name, opts, &callback )
+        ServicePoint.new( self, name, @defaults.merge( opts ), &callback )
 
       self
     end
@@ -270,7 +288,7 @@ module Needle
     # otherwise +nil+ is returned.
     def find_definition( name )
       point = @service_points[ name ]
-      point = @parent.find_definition( name ) if @parent unless point
+      point = parent.find_definition( name ) if parent unless point
       point
     end
 
@@ -279,13 +297,19 @@ module Needle
     # If the named service does not exist, ServiceNotFound is raised.
     #
     # Note that this returns the instantiated service, not the service point.
-    def []( name )
+    #
+    # Also, if any pipeline element in the instantiation pipeline does not
+    # support extra parameters when extra parameters have been given, then an
+    # error will be raised.
+    def get( name, *args )
       point = find_definition( name )
       raise ServiceNotFound, "#{fullname}.#{name}" unless point
 
-      point.instance
+      point.instance( *args )
     end
 
+    alias :[] :get
+
     # Returns +true+ if this container includes a service point with the given
     # name. Returns +false+ otherwise.
     def has_key?( name )
@@ -296,7 +320,7 @@ module Needle
     # service point with the given name. Returns +false+ otherwise.
     def knows_key?( name )
       return true if has_key?( name )
-      return @parent.knows_key?( name ) if @parent
+      return parent.knows_key?( name ) if parent
       false
     end
 
@@ -351,17 +375,9 @@ module Needle
     #
     #   container.register( :add ) { Adder.new }
     #   p container.add == container[:add] # => true
-    #
-    # This also allows you to register new services in the container by
-    # sending the container a message with an attached block.
-    #
-    # Usage:
-    #
-    #   container.foo { Bar.new }
-    #   p container.foo
-    def method_missing( sym, *args, &block )
-      if block.nil? && args.empty? && knows_key?( sym )
-        self[sym]
+    def method_missing( sym, *args )
+      if knows_key?( sym )
+        get( sym, *args )
       else
         super
       end
@@ -372,7 +388,36 @@ module Needle
     # this case, #has_key? is used instead of #knows_key? so that subcontainers
     # may be used as proper hashes by their parents.
     def respond_to?( sym )
-      @service_points.has_key?( sym ) || super
+      has_key?( sym ) || super
+    end
+
+    # Specifies a set of default options to use temporarily. The options are
+    # merged with the current set of defaults for the container. The original
+    # options are returned, and may be restored by invoking #use again with
+    # the hash that is returned. If a block is given, the registry will be
+    # yielded to it and the options automatically restored when the block
+    # returns.
+    def use( opts, &block ) # :yield: self
+      use! @defaults.merge( opts ), &block
+    end
+
+    # Specifies a set of default options to use temporarily. The original
+    # options are returned. This differs from #use in that it will completely
+    # replace the original options, instead of merging the parameters with
+    # the originals.
+    def use!( opts )
+      original = @defaults
+      @defaults = opts
+
+      if block_given?
+        begin
+          yield self
+        ensure
+          use! original
+        end
+      end
+
+      return original
     end
 
   end

data/lib/needle/definition-context.rb

@@ -30,7 +30,7 @@ module Needle
       protected_instance_methods +
       public_instance_methods -
       [ "instance_eval", "__id__", "__send__", "initialize", "remove_const",
-        "method_missing", "method", "class", "inspect", "to_s", "instance_variables" ]
+        "method_missing", "method", "class", "inspect", "to_s", "instance_variables", "block_given?" ]
     ).
     each { |m| undef_method m }
 
@@ -76,6 +76,38 @@ module Needle
       @container.__send__( :require, *parms )
     end
 
+    # Delegate to Container#use on the current container, but yields the
+    # definition context instead of the container.
+    def use( opts, &block )
+      use! @container.defaults.merge( opts ), &block
+    end
+
+    # Delegate to Container#use! on the current container, but yields the
+    # definition context instead of the container.
+    def use!( opts )
+      original = @container.use!( opts )
+
+      if block_given?
+        begin
+          yield self
+        ensure
+          @container.use! original
+        end
+      end
+
+      original
+    end
+
+    # Delegates to Container#has_key?.
+    def has_key?( name )
+      @container.has_key?( name )
+    end
+
+    # Delegates to Container#knows_key?.
+    def knows_key?( name )
+      @container.knows_key?( name )
+    end
+
     # Any method invocation with no block and no parameters is interpreted to
     # be a service reference on the wrapped container, and delegates to
     # Container#[]. If the block is not given but the args are not empty, a
@@ -85,11 +117,7 @@ module Needle
     # all parameters in place.
     def method_missing( sym, *args, &block )
       if block.nil?
-        if args.empty?
-          @container[sym]
-        else
-          super
-        end
+        @container.get( sym, *args )
       else
         @container.register( sym, *args, &block )
       end

data/lib/needle/lifecycle/multiton.rb

@@ -0,0 +1,64 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Needle dependency injection
+# library for Ruby. This file (and the library as a whole) may be used only as
+# allowed by either the BSD license, or the Ruby license (or, by association
+# with the Ruby license, the GPL). See the "doc" subdirectory of the Needle
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# needle website : http://needle.rubyforge.org
+# project website: http://rubyforge.org/projects/needle
+# =============================================================================
+#++
+
+require 'needle/pipeline/element'
+require 'needle/thread'
+
+module Needle
+  module Lifecycle
+
+    # The instantiation pipeline element that enforces the multiton
+    # multiplicity. "Multiton" multiplicity is like singleton multiplicity,
+    # except that the guarded instance is unique for each unique set of
+    # arguments passed to the multiton.
+    class Multiton < Needle::Pipeline::Element
+      set_default_priority 100
+
+      # Creates the mutex to use and initializes the cache.
+      def initialize_element
+        @mutex = QueryableMutex.new
+        @cached = Hash.new
+        @is_cached = Hash.new( false )
+      end
+
+      # Returns the cached reference for the given arguments, if it has been
+      # previously cached. Otherwise, invokes the next element in the pipeline
+      # and caches the result. The cached reference is returned.
+      def call( container, point, *args )
+        unless @is_cached[ args ]
+          @mutex.synchronize do
+            unless @is_cached[ args ]
+              @cached[ args ] = succ.call( container, point, *args )
+              @is_cached[ args ] = true
+            end
+          end
+        end
+
+        @cached[ args ]
+      end
+
+      # Resets the caches for this multiton object.
+      def reset!
+        @mutex.synchronize do
+          @cached = Hash.new
+          @is_cached = Hash.new( false )
+        end
+      end
+
+    end
+
+  end
+end