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.
- []
- builder
- define
- define!
- descended_from?
- find_definition
- fullname
- get
- has_key?
- intercept
- keys
- knows_key?
- method_missing
- namespace
- namespace!
- namespace_define
- namespace_define!
- new
- pipeline
- register
- require
- respond_to?
- root
- use
- use!
[R] | defaults | 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. |
[R] | name | The name of this container. May be nil. |
[R] | parent | The container that contains this container. This will be nil for the root of a hierarchy (see Registry). |
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.
[ show source ]
# File lib/needle/container.rb, line 48 48: def initialize( parent=nil, name=nil ) 49: @root = nil 50: @builder = nil 51: 52: @name = name 53: @parent = parent 54: @service_points = Hash.new 55: 56: @defaults = ( parent.nil? ? Hash.new : parent.defaults.dup ) 57: end
Alias for get
Returns the DefinitionContext instance that can be used to "build" this container.
[ show source ]
# File lib/needle/container.rb, line 87 87: def builder 88: @builder ||= self[ :definition_context_factory ].new( self ) 89: end
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 }
[ show source ]
# File lib/needle/container.rb, line 106 106: def define 107: yield builder if block_given? 108: builder 109: end
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
[ show source ]
# File lib/needle/container.rb, line 119 119: def define!( &block ) 120: raise ArgumentError, "block expected" unless block 121: builder.instance_eval( &block ) 122: self 123: end
Returns true if this container either is the given container or is descended from the given container, and false otherwise.
[ show source ]
# File lib/needle/container.rb, line 70 70: def descended_from?( container ) 71: return true if self == container 72: return false unless parent 73: parent.descended_from? container 74: end
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.
[ show source ]
# File lib/needle/container.rb, line 289 289: def find_definition( name ) 290: point = @service_points[ name ] 291: point = parent.find_definition( name ) if parent unless point 292: point 293: 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".
[ show source ]
# File lib/needle/container.rb, line 79 79: def fullname 80: parent_name = ( parent ? parent.fullname : nil ) 81: return @name.to_s unless parent_name 82: "#{parent_name}.#{@name}" 83: end
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.
[ show source ]
# File lib/needle/container.rb, line 304 304: def get( name, *args ) 305: point = find_definition( name ) 306: raise ServiceNotFound, "#{fullname}.#{name}" unless point 307: 308: point.instance( *args ) 309: end
Returns true if this container includes a service point with the given name. Returns false otherwise.
[ show source ]
# File lib/needle/container.rb, line 315 315: def has_key?( name ) 316: @service_points.has_key?( name ) 317: end
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 }
[ show source ]
# File lib/needle/container.rb, line 261 261: def intercept( name ) 262: point = find_definition( name ) 263: raise ServiceNotFound, "#{fullname}.#{name}" unless point 264: 265: interceptor = self[ :interceptor_impl_factory ].new 266: point.interceptor interceptor 267: 268: interceptor 269: end
Return an array of the names of all service points in this container.
[ show source ]
# File lib/needle/container.rb, line 328 328: def keys 329: @service_points.keys 330: end
Returns true if this container or any ancestor includes a service point with the given name. Returns false otherwise.
[ show source ]
# File lib/needle/container.rb, line 321 321: def knows_key?( name ) 322: return true if has_key?( name ) 323: return parent.knows_key?( name ) if parent 324: false 325: end
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
[ show source ]
# File lib/needle/container.rb, line 378 378: def method_missing( sym, *args ) 379: if knows_key?( sym ) 380: get( sym, *args ) 381: else 382: super 383: end 384: end
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.
[ show source ]
# File lib/needle/container.rb, line 174 174: def namespace( name, opts={}, &block ) 175: register( name, opts ) do |c,p| 176: ns = self[ :namespace_impl_factory ].new( c, name ) 177: block.call ns if block 178: ns 179: end 180: end
Alias for namespace_define!
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.
[ show source ]
# File lib/needle/container.rb, line 248 248: def namespace_define( name, opts={}, &block ) 249: raise ArgumentError, "block expected" unless block 250: namespace( name, opts ) { |ns| ns.define( &block ) } 251: self[name] 252: end
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.
[ show source ]
# File lib/needle/container.rb, line 211 211: def namespace_define!( name, opts={}, &block ) 212: raise ArgumentError, "block expected" unless block 213: namespace( name, opts ) { |ns| ns.define!( &block ) } 214: self[name] 215: end
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 ) }
[ show source ]
# File lib/needle/container.rb, line 279 279: def pipeline( name ) 280: point = find_definition( name ) 281: raise ServiceNotFound, "#{fullname}.#{name}" unless point 282: 283: point.pipeline 284: end
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
[ show source ]
# File lib/needle/container.rb, line 136 136: def register( name, opts={}, &callback ) 137: raise ArgumentError, "expect block" unless callback 138: 139: name = name.to_s.intern unless name.is_a?( Symbol ) 140: @service_points[ name ] = 141: ServicePoint.new( self, name, @defaults.merge( opts ), &callback ) 142: 143: self 144: end
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
[ show source ]
# File lib/needle/container.rb, line 353 353: def require( file, target_name, registration_method=:register_services ) 354: Kernel.require file 355: 356: if target_name.is_a?( Module ) 357: target = target_name 358: else 359: target = Object 360: target_name.to_s.split( /::/ ).each do |element| 361: target = target.const_get( element ) 362: end 363: end 364: 365: target.__send__( registration_method, self ) 366: end
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.
[ show source ]
# File lib/needle/container.rb, line 390 390: def respond_to?( sym ) 391: has_key?( sym ) || super 392: end
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.
[ show source ]
# File lib/needle/container.rb, line 62 62: def root 63: return @root if @root 64: return self if parent.nil? 65: @root = parent.root 66: 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.
[ show source ]
# File lib/needle/container.rb, line 400 400: def use( opts, &block ) # :yield: self 401: use! @defaults.merge( opts ), &block 402: 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.
[ show source ]
# File lib/needle/container.rb, line 408 408: def use!( opts ) 409: original = @defaults 410: @defaults = opts 411: 412: if block_given? 413: begin 414: yield self 415: ensure 416: use! original 417: end 418: end 419: 420: return original 421: end