needle 0.5.0

data/lib/needle/models/proxy.rb

@@ -0,0 +1,84 @@
+#--
+# =============================================================================
+# 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 'thread'
+
+module Needle
+  module Models
+
+    # A proxy class to aid in deferred instantiation of service points. This is
+    # used primarily by the "deferred" service models.
+    class Proxy
+
+      # Create a new proxy that wraps the given service point.
+      def initialize( container, &callback )
+        @container = container
+        @callback = callback
+        @mutex = Mutex.new
+        @instantiation_failed = false
+        @instance = nil
+      end
+
+      # Attempts to invoke the given message on the service. If the service has
+      # not yet been instantiated, it will be instantiated and stored.
+      def method_missing( sym, *args, &block )
+        unless @instance || @instantiation_failed
+          @mutex.synchronize do
+            unless @instance || @instantiation_failed
+              begin
+                @instance = @callback.call( @container )
+              rescue Exception
+                @instantiation_failed = true
+                raise
+              end
+            end
+          end
+        end
+
+        unless @instantiation_failed
+          @instance.__send__ sym, *args, &block
+        else
+          # just return nil... this way, a failed instantiation won't barf
+          # more than once... I hope...
+        end
+      end
+
+      # Override some "standard" methods so that they are routed to the
+      # service instead of to the proxy.
+      [ "is_a?", "respond_to?", "to_s", "to_str",
+        "to_i", "to_int", "to_io", "===", "==", "=~",
+        "send" ].each do |method|
+      #begin
+        class_eval <<-EOF
+          def #{method}( *args, &block )
+            unless @instantiation_failed
+              method_missing '#{method}', *args, &block
+            else
+              super
+            end
+          end
+        EOF
+      end
+
+      def inspect
+        "#<#{self.class.name}:#{"0x%08x"%self.id}:" +
+        "instantiated=>#{@instance ? true : false}>"
+      end
+
+    end
+
+  end
+end

data/lib/needle/models/singleton-deferred.rb

@@ -0,0 +1,57 @@
+#--
+# =============================================================================
+# 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/models/proxy'
+require 'thread'
+
+module Needle
+  module Models
+
+    # The definition of the "singleton-deferred" lifecycle service model.
+    # This will result in deferred instantiation of the requested service,
+    # with a new instance being returned the first time #instance is invoked,
+    # and that same instance returned every time thereafter.
+    #
+    # This model is thread-safe.
+    class SingletonDeferred
+
+      # Create a new SingletonDeferred service model.
+      def initialize( container, opts={}, &callback )
+        @container = container
+        @callback = callback
+        @mutex = Mutex.new
+        @instance = nil
+      end
+
+      # Return the cached instance, if it exists. Otherwise, create new
+      # Proxy instance that wraps the container and callback references of
+      # this service model, and cache it. Then return that instance.
+      #
+      # This method is thread-safe.
+      def instance
+        return @instance if @instance
+
+        @mutex.synchronize do
+          return @instance if @instance
+          @instance = Proxy.new( @container, &@callback )
+        end
+
+        return @instance
+      end
+    end
+
+  end
+end

data/lib/needle/models/singleton.rb

@@ -0,0 +1,56 @@
+#--
+# =============================================================================
+# 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 'thread'
+
+module Needle
+  module Models
+
+    # The definition of the "singleton" lifecycle service model. This will
+    # result in immediate instantiation of the requested service, with a new
+    # instance being returned the first time #instance is invoked, and that
+    # same instance returned every time thereafter.
+    #
+    # This model is thread-safe.
+    class Singleton
+
+      # Create a new instance of the singleton service model.
+      def initialize( container, opts={}, &callback )
+        @container = container
+        @callback = callback
+        @mutex = Mutex.new
+        @instance = nil
+      end
+
+      # Return the cached instance, if it exists. Otherwise, create new
+      # instance by invoking the registered callback, caching the result.
+      # Then return that instance.
+      #
+      # This method is thread-safe.
+      def instance
+        return @instance if @instance
+
+        @mutex.synchronize do
+          return @instance if @instance
+          @instance = @callback.call( @container )
+        end
+
+        return @instance
+      end
+    end
+
+  end
+end

data/lib/needle/models.rb

@@ -0,0 +1,44 @@
+#--
+# =============================================================================
+# 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/models/prototype'
+require 'needle/models/prototype-deferred'
+require 'needle/models/singleton'
+require 'needle/models/singleton-deferred'
+
+module Needle
+  module Models
+
+    # A convenience method for registering all standard service models with
+    # a container. This also defines a <tt>:service_models</tt> service,
+    # implemented as a Hash, which is used for keeping the references to
+    # installed service models.
+    #
+    # This method is called internally by Registry when it is instantiated,
+    # and should never be called directly.
+    def register( registry )
+      registry.register( :service_models, :model => Singleton ) { Hash.new }
+      registry[:service_models].update(
+        :singleton => Singleton,
+        :singleton_deferred => SingletonDeferred,
+        :prototype => Prototype,
+        :prototype_deferred => PrototypeDeferred
+      )
+    end
+    module_function :register
+
+  end
+end

data/lib/needle/registry.rb

@@ -0,0 +1,110 @@
+#--
+# =============================================================================
+# 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/container'
+require 'needle/errors'
+require 'needle/log-factory'
+require 'needle/logging-interceptor'
+require 'needle/models'
+
+module Needle
+
+  # Registry is a specialization of Container, with additional functionality
+  # for bootstrapping basic services into a new registry. It also supports a
+  # #new! method for easily registering new services.
+  #
+  # Usage:
+  #
+  #   require 'needle'
+  #
+  #   registry = Needle::Registry.new
+  #   registry.register( :foo ) { Foo.new }
+  #   registry.register( :bar ) { |c| Bar.new( c.foo ) }
+  #
+  #   bar = registry.bar
+  class Registry < Container
+
+    # This is the default name given to a registry. If you have multiple
+    # independent registries in the same application, it can help to given them
+    # each names. By default, the name is empty.
+    DEFAULT_REGISTRY_NAME = ""
+
+    # Instantiate a new Registry (via #new) and immediately invoke #register!
+    # using the given block.
+    #
+    # Usage:
+    #
+    #   registry = Needle::Registry.new! do
+    #     add { Adder.new }
+    #     ...
+    #   end
+    #
+    #   adder = registry.add
+    def self.new!( *parms, &block )
+      raise NeedleError, "needs a block" if block.nil?
+      new( *parms ) { |reg| reg.register!( &block ) }
+    end
+
+    # Instantiate a new Registry. If the first parameter is a string, it will
+    # be used as the name of this registry. If the next parameter is a Hash,
+    # it will be used as the options to use when bootstrapping the registry.
+    # (This includes options used to initialize the logger factory.
+    #
+    # If a block is given, the constructed registry instance is yielded to it.
+    #
+    # Usage:
+    #
+    #   registry = Needle::Registry.new
+    #
+    # or
+    #
+    #   registry = Needle::Registry.new do |reg|
+    #     reg.register( :add ) { Adder.new }
+    #   end
+    def initialize( *parms )
+      raise ArgumentError, "expected <= 2 arguments" if parms.length > 2
+      name = ( parms.first.is_a?( String ) ? parms.shift :
+        DEFAULT_REGISTRY_NAME )
+      opts = ( parms.first.is_a?( Hash ) ? parms.shift : {} )
+
+      if parms.length > 0
+        raise ArgumentError, "invalid parameter(s): #{parms.inspect}"
+      end
+
+      super( nil, name )
+      bootstrap( opts )
+
+      yield( self ) if block_given?
+    end
+
+    # Return the name of this registry, enclosed in square braces.
+    def fullname
+      "[#{super}]"
+    end
+
+    # Bootstraps the service models, logger factory, and logging interceptor
+    # services into the current registry. This is only called when a new
+    # registry is created.
+    def bootstrap( opts )
+      Models.register( self )
+      register( :logs ) { LogFactory.new( opts[:logs] || {} ) }
+      register( :logging_interceptor ) { LoggingInterceptor }
+    end
+    private :bootstrap
+
+  end
+
+end

data/lib/needle/service-point.rb

@@ -0,0 +1,109 @@
+#--
+# =============================================================================
+# 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/interceptor-chain'
+
+module Needle
+
+  # A "service point" is a definition of a service. Just as a class defines the
+  # behavior of an object, so does a service point describes a service. In
+  # particular, a service point also knows how to instantiate a service.
+  #
+  # A ServicePoint should never be directly instantiated. Instead, define
+  # services via the Container#register and Container#register! interfaces.
+  class ServicePoint
+
+    # The name of this service point, as it is known to the container that it
+    # was registered in.
+    attr_reader :name
+
+    # A reference to the container that contains this service point.
+    attr_reader :container
+
+    # Create a new service point that references the given container and has
+    # the given name. The associated callback will be used to instantiate the
+    # service on demand.
+    #
+    # The <tt>:model</tt> option is used to tell Needle which style of
+    # life-cycle management should be used for the service. It defaults to
+    # <tt>:singleton</tt>. The model should either be a class (which implements
+    # the necessary interface to be a service model), a symbol (in which case
+    # it refers to a service model that has been registered in the root
+    # <tt>:service_models</tt> service), or a string (in which case it is
+    # internalized and converted to a symbol). All other values are converted
+    # to strings and then internalized.
+    def initialize( container, name, opts={}, &callback )
+      @name = name
+      @container = container
+      @callback = callback
+      @interceptors = nil
+
+      model = opts[:model] || :singleton
+
+      case model
+        when Class then
+          model_factory = model
+        when Symbol then
+          model_factory = @container.root.service_models[model]
+        when String then
+          model = model.intern
+          model_factory = @container.root.service_models[model]
+        else
+          model = model.to_s.intern
+          model_factory = @container.root.service_models[model]
+      end
+
+      @model = model_factory.new( @container, opts ) { instantiate }
+    end
+
+    # Returns the fully-qualified name of the service point, with the point's
+    # name, its container's name, and all of its container's ancestors' names
+    # concatenated together with dot characters, i.e. "one.two.three".
+    def fullname
+      "#{@container.fullname}.#{@name}"
+    end
+
+    # Adds the given interceptor definition to this service point. The
+    # parameter should act like an instance of Interceptor.
+    def interceptor( interceptor )
+      @interceptors ||= []
+      @interceptors.push interceptor
+    end
+
+    # Return the service instance represented by this service point. Depending
+    # on the style of lifecycle management chosen for this service point, this
+    # may or may not be a new instance for every invocation of this method.
+    def instance
+      @model.instance
+    end
+    
+    # Do the dirty-work of instantiating this service point. This invokes the
+    # callback that was registered for this service point, installs any
+    # requested interceptors, and returns the new instance.
+    def instantiate
+      instance = @callback.call( @container )
+
+      if @interceptors
+        instance = InterceptorChainBuilder.build( self, instance, @interceptors )
+      end
+
+      instance
+    end
+    private :instantiate
+
+  end
+
+end

data/lib/needle/version.rb

@@ -0,0 +1,28 @@
+#--
+# =============================================================================
+# 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
+# =============================================================================
+#++
+
+module Needle
+  module Version
+
+    MAJOR = 0
+    MINOR = 5
+    TINY  = 0
+    
+    # The version of the Needle library in use.
+    STRING = [ MAJOR, MINOR, TINY ].join( "." )
+
+  end
+end

data/lib/needle.rb

@@ -0,0 +1,54 @@
+#--
+# =============================================================================
+# 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
+# =============================================================================
+#++
+
+#--
+# Documentation Roadmap:
+#
+# The following items will given you sufficient background to understand how to
+# use the Needle API in your own programs.
+#
+#   1. Start with needle/registry.rb. This describes how to create a new
+#      service registry.
+#
+#   2. Then, read needle/container.rb. This describes the interface of the
+#      registry and namespaces.
+#
+# The following items are only necessary if you want to understand how Needle
+# works internally. You will rarely (if ever) need to use these interfaces
+# directly in your own programs:
+#
+#   1. needle/service-point.rb. This describes how services are instantiated.
+#
+#   2. needle/models.rb and needle/models/*.rb. These describe the service
+#      models that are available, which are used to manage the lifecycles of
+#      instantiated services.
+#
+#   3. needle/interceptor.rb. This describes the interface for configuring
+#      interceptors on services.
+#
+#   4. needle/interceptor-builder.rb. This describes the routines for
+#      constructing the proxy objects and interceptor chains around services.
+#
+#   5. needle/log-factory.rb and needle/logger.rb. These define the logging
+#      interface for needle.
+#
+#   6. needle/logging-interceptor.rb. This defines the logging interceptor
+#      service, which wraps every method of a service and logs tracing
+#      information.
+#++
+
+require 'needle/errors'
+require 'needle/registry'

data/test/ALL-TESTS.rb

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+#--
+# =============================================================================
+# 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
+# =============================================================================
+#++
+
+$:.unshift "../lib"
+
+Dir.chdir File.dirname(__FILE__)
+Dir["**/tc_*.rb"].each { |file| load file }

data/test/models/tc_prototype.rb

@@ -0,0 +1,53 @@
+#--
+# =============================================================================
+# 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
+# =============================================================================
+#++
+
+$:.unshift "../../lib"
+
+require "needle/models/prototype"
+require "test/unit"
+
+class TC_ModelsPrototype < Test::Unit::TestCase
+
+  def test_instance
+    instantiated = false
+    model = Needle::Models::Prototype.new( nil ) { 
+      instantiated = true
+      Hash.new
+    }
+
+    assert !instantiated
+    proto = model.instance
+    assert instantiated
+    proto[:test] = :value
+    assert_equal :value, proto[:test]
+  end
+
+  def test_container
+    model = Needle::Models::Prototype.new( :container ) { |c|
+      assert_equal :container, c
+      Hash.new
+    }
+    model.instance
+  end
+
+  def test_model
+    model = Needle::Models::Prototype.new( nil ) { Hash.new }
+    p1 = model.instance
+    p2 = model.instance
+    assert_not_same p1, p2
+  end
+
+end

data/test/models/tc_prototype_deferred.rb

@@ -0,0 +1,54 @@
+#--
+# =============================================================================
+# 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
+# =============================================================================
+#++
+
+$:.unshift "../../lib"
+
+require "needle/models/prototype-deferred"
+require "test/unit"
+
+class TC_ModelsPrototypeDeferred < Test::Unit::TestCase
+
+  def test_instance
+    instantiated = false
+    model = Needle::Models::PrototypeDeferred.new( nil ) { 
+      instantiated = true
+      Hash.new
+    }
+
+    assert !instantiated
+    proto = model.instance
+    assert !instantiated
+    proto[:test] = :value
+    assert instantiated
+    assert_equal :value, proto[:test]
+  end
+
+  def test_container
+    model = Needle::Models::PrototypeDeferred.new( :container ) { |c|
+      assert_equal :container, c
+      Hash.new
+    }
+    model.instance[:test] = :value
+  end
+
+  def test_model
+    model = Needle::Models::PrototypeDeferred.new( nil ) { Hash.new }
+    p1 = model.instance
+    p2 = model.instance
+    assert_not_same p1, p2
+  end
+
+end