Class: Needle::Container

### Home Classes Methods

### In Files

- lib/needle/container.rb

### Parent

Object

### Methods

- ::new
- #[]
- #builder
- #define
- #define!
- #descended_from?
- #find_definition
- #fullname
- #get
- #has_key?
- #intercept
- #keys
- #knows_key?
- #method_missing
- #namespace
- #namespace!
- #namespace_define
- #namespace_define!
- #pipeline
- #register
- #require
- #respond_to?
- #root
- #use
- #use!

### Files

- README

### Class/Module Index

Quicksearch

- Needle
- Needle::Bug
- Needle::Container
- Needle::DefinitionContext
- Needle::IncludeExclude
- Needle::Interceptor
- Needle::Interceptor::DynamicInterceptor
- Needle::InterceptorChainBuilder
- Needle::InterceptorChainBuilder::InterceptedServiceProxy
- Needle::InterceptorChainBuilder::InterceptorChainElement
- Needle::InterceptorChainBuilder::ProxyObjectChainElement
- Needle::InterceptorConfigurationError
- Needle::Lifecycle
- Needle::Lifecycle::Deferred
- Needle::Lifecycle::Initialize
- Needle::Lifecycle::Multiton
- Needle::Lifecycle::Proxy
- Needle::Lifecycle::Singleton
- Needle::Lifecycle::Threaded
- Needle::LogFactory
- Needle::Logger
- Needle::LoggingInterceptor
- Needle::NeedleError
- Needle::Pipeline
- Needle::Pipeline::Collection
- Needle::Pipeline::Collection::BlockElement
- Needle::Pipeline::Element
- Needle::Pipeline::InterceptorElement
- Needle::QueryableMutex
- Needle::Registry
- Needle::ServiceNotFound
- Needle::ServicePoint
- Needle::Version

No matching classes.

# Needle::Container

The container is the heart of Needle's model. Every Container instance is a miniature registry, and is really a namespace separate from every other Container instance. Service lookups inside of a container always look in `self` first, and if not found, they then look in their parent container, recursively.

You will rarely need to instantiate a Container directly. Instead, use the Container#namespace method to create new containers.

### Attributes

defaults[R]

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.

name[R]

The name of this container. May be `nil`.

parent[R]

The container that contains this container. This will be `nil` for the root of a hierarchy (see Registry).

### Public Class Methods

new( parent=nil, name=nil ) click to toggle source

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.

    # File lib/needle/container.rb, line 48
    def initialize( parent=nil, name=nil )
      @root = nil
      @builder = nil

      @name = name
      @parent = parent
      @service_points = Hash.new

      @defaults = ( parent.nil? ? Hash.new : parent.defaults.dup )
    end

### Public Instance Methods

[]( name, *args ) click to toggle source
Alias for: get
builder() click to toggle source

Returns the DefinitionContext instance that can be used to "build" this container.

    # File lib/needle/container.rb, line 87
    def builder
      @builder ||= self[ :definition_context_factory ].new( self )
    end

define() click to toggle source

If a block is given, yields the container's builder instance to the block. Otherwise, simply returns the builder instance.

Usage:

    container.define do |b|
      b.foo { Bar.new }
      b.baz { Baz.new }
      ...
    end

Or:

    container.define.foo { Bar.new }
    container.define.baz { Baz.new }

    # File lib/needle/container.rb, line 106
    def define
      yield builder if block_given?
      builder
    end

define!( &block ) click to toggle source

Create a new DefinitionContext around the container, and then evaluate the block within the new context instance (via `instance_eval`).

Usage:

    container.define! do
      calc( :model => :prototype ) { Calc.new( operations ) }
    end

    # File lib/needle/container.rb, line 119
    def define!( &block )
      raise ArgumentError, "block expected" unless block
      builder.instance_eval( &block )
      self
    end

descended_from?( container ) click to toggle source

Returns `true` if this container either is the given container or is descended from the given container, and `false` otherwise.

    # File lib/needle/container.rb, line 70
    def descended_from?( container )
      return true if self == container
      return false unless parent
      parent.descended_from? container
    end

find_definition( name ) click to toggle source

Searches the current container and its ancestors for the named service. If found, the service point (the definition of that service) is returned, otherwise `nil` is returned.

    # File lib/needle/container.rb, line 289
    def find_definition( name )
      point = @service_points[ name ]
      point = parent.find_definition( name ) if parent unless point
      point
    end

fullname() click to toggle source

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".

    # File lib/needle/container.rb, line 79
    def fullname
      parent_name = ( parent ? parent.fullname : nil )
      return @name.to_s unless parent_name
      "#{parent_name}.#{@name}"
    end

get( name, *args ) click to toggle source

Retrieves the named service, if it exists. Ancestors are searched if the service is not defined by the current container (see find_definition). If the named service does not exist, ServiceNotFound is raised.

Note that this returns the instantiated service, not the service point.

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.

    # File lib/needle/container.rb, line 304
    def get( name, *args )
      point = find_definition( name )
      raise ServiceNotFound, "#{fullname}.#{name}" unless point

      point.instance( self, *args )
    end

Also aliased as: []
has_key?( name ) click to toggle source

Returns `true` if this container includes a service point with the given name. Returns `false` otherwise.

    # File lib/needle/container.rb, line 315
    def has_key?( name )
      @service_points.has_key?( name )
    end

intercept( name ) click to toggle source

Describe a new interceptor to use that will intercept method calls on the named service. This method returns a new Interceptor instance, which can be used directly to configure the behavior of the interceptor.

Usage:

    container.intercept( :calc ).with { |c| c.logging_interceptor }

    # File lib/needle/container.rb, line 261
    def intercept( name )
      point = find_definition( name )
      raise ServiceNotFound, "#{fullname}.#{name}" unless point

      interceptor = self[ :interceptor_impl_factory ].new
      point.interceptor interceptor

      interceptor
    end

keys() click to toggle source

Return an array of the names of all service points in this container.

    # File lib/needle/container.rb, line 328
    def keys
      @service_points.keys
    end

knows_key?( name ) click to toggle source

Returns `true` if this container or any ancestor includes a service point with the given name. Returns `false` otherwise.

    # File lib/needle/container.rb, line 321
    def knows_key?( name )
      return true if has_key?( name )
      return parent.knows_key?( name ) if parent
      false
    end

method_missing( sym, *args ) click to toggle source

As a convenience for accessing services, this delegates any message sent to the container (which has no parameters and no block) to Container#[]. Note that this incurs slightly more overhead than simply calling Container#[] directly, so if performance is an issue, you should avoid this approach.

Usage:

    container.register( :add ) { Adder.new }
    p container.add == container[:add] # => true

    # File lib/needle/container.rb, line 378
    def method_missing( sym, *args )
      if knows_key?( sym )
        get( sym, *args )
      else
        super
      end
    end

namespace( name, opts={}, &block ) click to toggle source

Create a new namespace within the container, with the given name. If a block is provided, it will be invoked when the namespace is created, with the new namespace passed to it.

For the curious, namespaces are simply services that are implemented by Container. The two statements are conceptually identical:

    container.namespace( :calc )
    container.register( :calc ) { |c,p| Needle::Container.new( c, p.name ) }

Note that this means that namespaces may be singletons or prototypes, or have immediate or deferred instantiation, and so forth. (The default of immediate, singleton instantiation is sufficient for 99% of the things you'll use namespaces for.)

Usage:

    container.namespace( :operations ) do |op|
      op.register( :add ) { Adder.new }
      ...
    end

    adder = container.calc.operations.add

Note: the block is not invoked until the namespace is created, which is not until it is first referenced. If you need the namespace to be created immediately, either use namespace_define or reference the namespace as soon as you've created it.

    # File lib/needle/container.rb, line 174
    def namespace( name, opts={}, &block )
      register( name, opts ) do |c,p|
        ns = self[ :namespace_impl_factory ].new( c, name )
        block.call ns if block
        ns
      end
    end

namespace!( name, opts={}, &block ) click to toggle source
Alias for: namespace_define!
namespace_define( name, opts={}, &block ) click to toggle source

Create a new namespace within the container, with the given name. The block (which is required) will be passed to Container#define on the new namespace.

For the curious, namespaces are simply services that are implemented by Container. The two statements are really identical:

    container.namespace( :calc )
    container.register( :calc ) { |c,p| Needle::Container.new( c, p.name ) }

Note that this means that namespaces may be singletons or prototypes, or have immediate or deferred instantiation, and so forth. (The default of immediate, singleton instantiation is sufficient for 99% of the things you'll use namespaces for.)

Usage:

    container.namespace_define( :operations ) do |b|
      b.add { Adder.new }
      ...
    end

    adder = container.calc.operations.add

Note: this method will immediately instantiate the new namespace, unlike namespace. If you want instantiation of the namespace to be deferred, either use a deferring service model (like `:singleton_deferred`) or create the namespace via namespace.

    # File lib/needle/container.rb, line 248
    def namespace_define( name, opts={}, &block )
      raise ArgumentError, "block expected" unless block
      namespace( name, opts ) { |ns| ns.define( &block ) }
      self[name]
    end

namespace_define!( name, opts={}, &block ) click to toggle source

Create a new namespace within the container, with the given name. The block (which is required) will be passed to Container#define! on the new namespace.

For the curious, namespaces are simply services that are implemented by Container. The two statements are really identical:

    container.namespace( :calc )
    container.register( :calc ) { |c,p| Needle::Container.new( c, p.name ) }

Note that this means that namespaces may be singletons or prototypes, or have immediate or deferred instantiation, and so forth. (The default of immediate, singleton instantiation is sufficient for 99% of the things you'll use namespaces for.)

Usage:

    container.namespace_define!( :operations ) do
      add { Adder.new }
      ...
    end

    adder = container.calc.operations.add

Note: this method will immediately instantiate the new namespace, unlike namespace. If you want instantiation of the namespace to be deferred, either use a deferring service model (like `:singleton_deferred`) or create the namespace via namespace.

    # File lib/needle/container.rb, line 211
    def namespace_define!( name, opts={}, &block )
      raise ArgumentError, "block expected" unless block
      namespace( name, opts ) { |ns| ns.define!( &block ) }
      self[name]
    end

Also aliased as: namespace!
pipeline( name ) click to toggle source

Returns the pipeline object for the named service, which allows clients to explicitly manipulate the service's instantiation pipeline.

Usage:

    container.pipeline( :calc ).
      add( :initialize ).
      add( :custom ) { |me,*args| me.succ.call( *args ) }

    # File lib/needle/container.rb, line 279
    def pipeline( name )
      point = find_definition( name )
      raise ServiceNotFound, "#{fullname}.#{name}" unless point

      point.pipeline
    end

register( name, opts={}, &callback ) click to toggle source

Register the named service with the container. When the service is requested (with Container#[]), the associated callback will be used to construct it.

This returns the registry that was used to register the service.

Usage:

    container.register( :calc, :model=>:prototype ) do |c|
      Calc.new( c.operations )
    end

    # File lib/needle/container.rb, line 136
    def register( name, opts={}, &callback )
      raise ArgumentError, "expect block" unless callback

      name = name.to_s.intern unless name.is_a?( Symbol )
      @service_points[ name ] =
        ServicePoint.new( self, name, @defaults.merge( opts ), &callback )

      self
    end

require( file, target_name, registration_method=:register_services ) click to toggle source

Require the given file, and then invoke the given registration method on the target module. The container will be passed as the sole parameter to the registration method. This allows you to easily decentralize the definition of services.

Usage:

    container.require( "app/services", "App::Services" )

    # in app/services.rb:

    module App
      module Services

        def register_services( container )
          ...
        end
        module_function :register_services

      end
    end

    # File lib/needle/container.rb, line 353
    def require( file, target_name, registration_method=:register_services )
      Kernel.require file

      if target_name.is_a?( Module )
        target = target_name
      else
        target = Object
        target_name.to_s.split( /::/ ).each do |element|
          target = target.const_get( element )
        end
      end

      target.__send__( registration_method, self )
    end

respond_to?( sym ) click to toggle source

Returns true if this container responds to the given message, or if it explicitly contains a service with the given name (see has_key?). In this case, has_key? is used instead of knows_key? so that subcontainers may be used as proper hashes by their parents.

    # File lib/needle/container.rb, line 390
    def respond_to?( sym )
      has_key?( sym ) || super
    end

root() click to toggle source

Returns the root of the current hierarchy. If the container is the root, returns self, otherwise calls Container#root on its parent. The value is cached for future reference.

    # File lib/needle/container.rb, line 62
    def root
      return @root if @root
      return self if parent.nil?
      @root = parent.root
    end

use( opts ) click to toggle source

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.

    # File lib/needle/container.rb, line 400
    def use( opts, &block ) # :yield: self
      use! @defaults.merge( opts ), &block
    end

use!( opts ) click to toggle source

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.

    # File lib/needle/container.rb, line 408
    def use!( opts )
      original = @defaults
      @defaults = opts

      if block_given?
        begin
          yield self
        ensure
          use! original
        end
      end

      return original
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.