Class: Needle::Container

Inherits:
Object
  • Object
show all
Defined in:
lib/needle/container.rb

Overview

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.

Direct Known Subclasses

Registry

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(parent = nil, name = nil) ⇒ Container

Create a new empty container with the given parent and name.



40
41
42
43
44
45
46
47
 
# File 'lib/needle/container.rb', line 40

def initialize( parent=nil, name=nil )
  @root = nil
  @builder = nil

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

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(sym, *args, &block) ⇒ Object

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

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



362
363
364
365
366
367
368
 
# File 'lib/needle/container.rb', line 362

def method_missing( sym, *args, &block )
  if block.nil? && args.empty? && knows_key?( sym )
    self[sym]
  else
    super
  end
end

Instance Attribute Details

#name ⇒ Object (readonly)

The name of this container. May be nil.



37
38
39
 
# File 'lib/needle/container.rb', line 37

def name
  @name
end

#parent ⇒ Object (readonly)

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



34
35
36
 
# File 'lib/needle/container.rb', line 34

def parent
  @parent
end

Instance Method Details

#[](name) ⇒ Object

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.

Raises:



282
283
284
285
286
287
 
# File 'lib/needle/container.rb', line 282

def []( name )
  point = find_definition( name )
  raise ServiceNotFound, "#{fullname}.#{name}" unless point

  point.instance
end

#builder ⇒ Object

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



69
70
71
 
# File 'lib/needle/container.rb', line 69

def builder
  @builder ||= self[ :definition_context_factory ].new( self )
end

#define {|builder| ... } ⇒ Object

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 }

Yields:



88
89
90
91
 
# File 'lib/needle/container.rb', line 88

def define
  yield builder if block_given?
  builder
end

#define!(&block) ⇒ Object

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

Raises:

  • (ArgumentError) 


101
102
103
104
105
 
# File 'lib/needle/container.rb', line 101

def define!( &block )
  raise ArgumentError, "block expected" unless block
  builder.instance_eval( &block )
  self
end

#find_definition(name) ⇒ Object

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.



271
272
273
274
275
 
# File 'lib/needle/container.rb', line 271

def find_definition( name )
  point = @service_points[ name ]
  point = @parent.find_definition( name ) if @parent unless point
  point
end

#fullname ⇒ Object

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



61
62
63
64
65
 
# File 'lib/needle/container.rb', line 61

def fullname
  parent_name = ( @parent ? @parent.fullname : nil )
  return @name.to_s unless parent_name
  "#{parent_name}.#{@name}"
end

#has_key?(name) ⇒ Boolean

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

Returns:

  • (Boolean) 


291
292
293
 
# File 'lib/needle/container.rb', line 291

def has_key?( name )
  @service_points.has_key?( name )
end

#intercept(name) ⇒ Object

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 }

Raises:



243
244
245
246
247
248
249
250
251
 
# File 'lib/needle/container.rb', line 243

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 ⇒ Object

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



304
305
306
 
# File 'lib/needle/container.rb', line 304

def keys
  @service_points.keys
end

#knows_key?(name) ⇒ Boolean

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

Returns:

  • (Boolean) 


297
298
299
300
301
 
# File 'lib/needle/container.rb', line 297

def knows_key?( name )
  return true if has_key?( name )
  return @parent.knows_key?( name ) if @parent
  false
end

#namespace(name, opts = {}, &block) ⇒ Object

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.



156
157
158
159
160
161
162
 
# File 'lib/needle/container.rb', line 156

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_define(name, opts = {}, &block) ⇒ Object

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.

Raises:

  • (ArgumentError) 


230
231
232
233
234
 
# File 'lib/needle/container.rb', line 230

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) ⇒ Object Also known as: namespace!

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.

Raises:

  • (ArgumentError) 


193
194
195
196
197
 
# File 'lib/needle/container.rb', line 193

def namespace_define!( name, opts={}, &block )
  raise ArgumentError, "block expected" unless block
  namespace( name, opts ) { |ns| ns.define!( &block ) }
  self[name]
end

#pipeline(name) ⇒ Object

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 ) }

Raises:



261
262
263
264
265
266
 
# File 'lib/needle/container.rb', line 261

def pipeline( name )
  point = find_definition( name )
  raise ServiceNotFound, "#{fullname}.#{name}" unless point

  point.pipeline
end

#register(name, opts = {}, &callback) ⇒ Object

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

Raises:

  • (ArgumentError) 


118
119
120
121
122
123
124
125
126
 
# File 'lib/needle/container.rb', line 118

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, opts, &callback )

  self
end

#require(file, target_name, registration_method = :register_services) ⇒ Object

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



329
330
331
332
333
334
335
336
337
338
339
340
341
342
 
# File 'lib/needle/container.rb', line 329

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) ⇒ Boolean

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.

Returns:

  • (Boolean) 


374
375
376
 
# File 'lib/needle/container.rb', line 374

def respond_to?( sym )
  @service_points.has_key?( sym ) || super
end

#root ⇒ Object

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.



52
53
54
55
56
 
# File 'lib/needle/container.rb', line 52

def root
  return @root if @root
  return self if parent.nil?
  @root = parent.root
end