Needle FAQ

What is a… container?

A container is collection of service points and other containers. It is used to organize services. Each container has access to all of the service points in its ancestor containers.

What is a… registry?

A registry is a special kind of container that has no parent container. It also defines a few services (such as the LoggingInterceptor, and the various service models and pipeline elements), so that they are available by default to all of the services it contains.

What is a… service point?

A service point is the definition of a service. Just as a class is the definition of an object, and you instantiate an object from a class, so do you instantiate services from service points.

What is a… service?

A service is the instantiation of a service point.

What is a… parameterized service?

A parameterized service is a service that allows contextual parameters to be passed to the service when it is created. Such services are typically used in conjunction with the multiton service model, but the only real requirement is that they not be used with a service model that does not support multiple parameters (like singleton or threaded).

What is a… service model?

A service model is a description of the lifecycle of a service. By default, all services are singletons, meaning that every time you ask a container for a particular service, you’ll get the same object instance back.

There are other service models available, though, including “prototype” (which returns a new instance for each request of a service) and “deferred” (which returns a proxy, deferring the instatiation of the service itself until a method is invoked on the service).

What is a… interceptor?

An interceptor is an object that may be placed between the client and a service. Every request to the service is thus intercepted by that object, which can do operations on the request (such as logging) and may even reroute or ignore the request altogether. This provides a kind of “poor man’s AOP”, since you can do “before”, “after”, and “around” advice on the methods of a service.

Needle comes with one standard interceptor, the LoggingInterceptor. It will log a message on method entry and exit, and also when an exception is raised.

What is a… pipeline?

In Needle, the instantiation pipeline is used to control how and when services are instantiated. The service models are implemented as pipelines.

Just as the interceptors are for hooking into method invocations, the pipelines are for hooking into service instantiations. Every time a service is requested, it’s instantiation pipeline is executed. By choosing the appropriate kinds of pipeline elements, all of the available service models can be implemented (prototype, prototype_deferred, singleton, singleton_deferred, etc.).

How do I… create a new registry?

There are several ways to create a new registry. The simplist is just to invoke Registry#new.

  reg = Needle::Registry.new

This will create a new Registry instance. You can also send a block to #new, in which case the new registry will be yielded to it:

  reg = Needle::Registry.new do |r|
    ...
  end

There are two other factory methods you can use for creating a Registry instance. Both require a block.

  r1 = Needle::Registry.define do |builder|
    ...
  end

  r2 = Needle::Registry.define! do
    ...
  end

Registry#define creates a “builder” object that you can use define services more conveniently. Register#define! (with a bang) does the same thing, but evaluates the block within the context of the builder.

How do I… register a service?

The first way to register a service is by calling #register on the registry (or a namespace):

  reg.register( :foo ) { Foo.new }

The (first) parameter to #register is the name of the service, and the block should return the implementation of the service. If needed, the block can accept two parameters—the container that the service is being registered with, and an object that represents the service being defined (called a “service point”):

  reg.register( :foo ) do |container,point|
    Foo.new( container[:bar], point.fullname )
  end

You can also use Container#define and Container#define! to register services. These approaches are friendlier if you are needing to register several services at once.

  reg.define do |builder|
    builder.foo { Foo.new }
    builder.bar { |c,p| Bar.new( c[:foo], p.name ) }
  end

  reg.define! do
    baz { |c,p| Baz.new( c[:bar], p.name ) }
    zoom { Buggy.new }
  end

Container#define yields a new “builder” object to the block. Messages sent to the builder are interpreted as service names, and if a block is sent with the message, a new service is registered under that name.

Container#define! does likewise, except it evaluates the block within the context of the builder object.

If you do not pass a block to #define, it will return the builder object, so you could do something like the following if you only need to define one or two services:

  reg.define.foo { ... }

Lastly, you can get the builder directly and add services using it:

  builder = reg.builder
  builder.baz { ... }
  builder.bar { ... }

(This last is the same as calling #define without arguments, but is more readable if you intend to use the builder object multiple times.)

How do I… reference a service?

Referencing a service can be done in either of two ways. The first is to treat the container (i.e., registry) as a hash, passing the name of the service as an argument to Container#[]:

  svc = registry[:foo]
  svc.do_something_interesting

A more convenient (but slightly more peril-fraught) approach is to send the name of the method to the registry as a message:

  svc = registry.foo

Be aware that this latter approach will only work when the service name does not conflict with the name of an existing method on the container. For example, if you were to do:

  registry.register( :hash ) { "hello, world" }
  p registry.hash

You would get the hash value of the registry object, instead of the value value of the service (which would be “hello, world”).

How do I… select a service model for a service (i.e., change the default model of lifecycle management)?

By default, a service will be managed as a singleton, i.e., every request of that service will return the same object instance. This is the singleton service model.

To select a different service model, pass it as an option when you register the service:

  registry.register( :foo, :model => :prototype ) {...}
  registry.define.bar( :model => :threaded ) {...}
  registry.define! do
    baz( :model => :singleton_deferred ) {...}
    ...
  end
  ...
How do I… create a namespace?

Namespaces allow you to organize your services into hierarchical packages. You can create namespaces in a few ways. The first (and simplest) is to just call Container#namespace:

  registry.namespace( :stuff )

This will create a namespace in the registry, called stuff. If you send a block as well, the block will be invoked (with the new namespace yielded to it) the first time the namespace is requested:

  registry.namespace( :stuff ) do |ns|
    ns.register( :foo ) {...}
    ns.define.bar {...}
    ns.define! do
      baz {...}
      buf {...}
    end
  end
Because it is so common to immediately define services on the new namespace, there are some convenience methods to make this more… convenient.
  registry.namespace_define!( :stuff ) do
    foo {...}
    bar {...}
    baz {...}
  end

  registry.namespace_define( :more_stuff ) do |b|
    b.blah {...}
    b.argh {...}
    b.hack {...}
  end

The first one, above, creates the namespace and calls Container#define!. The second creates the namespace and calls Container#define. In both cases, the namespace is created immediately, unlike Container#namespace which only creates the namespace when it is first requested.

Lastly, note that namespace’s are just special services. Thus, you can pass options to the namespace methods just as you can with Container#register and friends.

How do I… write log messages?

You can obtain a new logger instance from the :logs and :log_for services. Once you have a logger instance, you can invoke the #debug, #info, #warn, #error, and #fatal methods on the instance to log messages of the corresponding severity.

  logger = registry.logs.get( "a name for my logger" )
  logger.debug "This is a debug message" 
  logger.info "This is an informational message" 
  ...
  logger2 = registry.log_for( "another logger name" )
  ...

The two approaches shown above are identical—the second approach (using the log_for service) is just a convenience for logs.get.

Log messages are written, by default, to a file called “needle.log”, in the same directory that the application was invoked from.

You can also use a logging interceptor to automatically log all external method invocations on a service. This includes method entry and exit, as well as any exceptions that are raised inside the method.

  registry.register( :foo ) { ... }
  registry.intercept( :foo ).with { |r| r.logging_interceptor }

  foo.something
  foo.another_method( 1, 2, 3 )

See the chapter in the User’s Manual about logging for more information on how to use and configure loggers.

How do I… exclude methods from being intercepted?

Only interceptors that explicitly support exclusion of methods can help you here. Fortunately, the LoggingInterceptor is one of them. (If you write your own interceptor and would like similar functionality, see the IncludeExclude module.)

In the case of the LoggingInterceptor, just pass an array of patterns (matching method names and/or arities) as the “exclude” option, when declaring the interceptor:

  registry.register( :foo ) { ... }
  registry.intercept( :foo ).
    with { |r| r.logging_interceptor }.
    with_options :exclude => [ 'foo', 'bar(>4)', '*(<2)' ]

The above will exclude from interception any method named ‘foo’, or any invocation of ‘bar’ with more than 4 arguments, or any method invocation with fewer than two arguments.

You can also give an array of patterns to include. These cause methods to be explicitly intercepted even if they match an exclude pattern:

  registry.register( :foo ) { ... }
  registry.intercept( :foo ).
    with { |r| r.logging_interceptor }.
    with_options :exclude => [ 'foo', 'bar(>4)', '*(<2)' ],
                 :include => [ 'baz' ]

  foo = registry.foo
  foo.baz

This would result in the call to #baz being intercepted, even though it matches an exclude pattern (*(<2)).

How do I… include services defined in another library?

This requires that the other library be implemented in such a way that it expects to be “included” by other libraries/applications. For example, Needle encourages the use of a method called register_services, which accepts a container as a parameter:

  module A
    module B
      def register_services( container )
        ...
      end
      module_function :register_services
    end
  end

If the library has been implemented in this way, you can simply do a require of the library and then invoke the register_services method.

There is a convenience method in Container for doing this. Just call Container#require, passing the file to require and a string (or symbol) identifying the name of the module that contains the registration method. You can also pass a symbol as the third parameter naming the registration method, but it defaults to :register_services.

  require 'a/b'
  A::B.register_services( container )

  # or

  container.require( 'a/b', "A::B" )

The definition context (i.e., the “builder” object) also supports the require method, so you can do:

  container.define do |b|
    b.require "a/b", "A::B" 
    b.foo { ... }
    ...
  end
When should I… use a different service model? Like, :prototype?

The prototype service model is appropriate when the service:

For example, if you have a GUI library, a “button” service could be a prototype, because you will likely have many buttons in an application, with each button being an independent instance.

When should I… use a different service model? Like, :singleton?

The singleton service model is the default, so you should rarely need to explicitly specify it as a model. It is appropriate for services that:

When should I… use a different service model? Like, :threaded?

Threaded is similar to singleton, but it allows one unique instance of the service per thread. Thus, it is appropriate to the same situations as singleton, but specific to a thread, instead of an application. This is useful for web applications that are run in a single virtual machine, and which share a single registry.

When should I… use a different service model? Like, deferred?

Deferred models use a proxy to enforce lazy initialization of the service. A service using a deferred service model (ie, :prototype_deferred, :multiton_deferred, :singleton_deferred, or :threaded_deferred) will not be instantiated until the first time a method is invoked on the service.

This makes a deferred model appropriate when a service is expensive to instantiate, since you can wait to do the expensive initialization until it is really needed. Applications will start up faster when their dependences use deferred instantiation.

When should I… use a different service model? Like, initialize?

This is useful when you have a method that you want to be invoked automatically after a service has been instantiated. Consider the case where a service is initialized primarily using setters, but requires some logic to be executed to complete the initialization phase. In this case, you could always explicitly invoke the initialization method(s) in the constructor block, but if many services use the same initialization method, it can be more convenient to use an “initialize” service model.

When should I… use a different service model? Like, multiton?

Multitons are useful for factories, where you have a class that differentiates its instances based on some construction parameters that need to be determined at runtime. Thus, multitons are always used with parameterized services.