---
- "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.
- "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.
- "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.
- "service?": >-
A _service_ is the instantiation of a service point.
- "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@).
- "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).
- "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.
- "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.
- "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.)
- "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").
- "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
...
- "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.
- "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":http://needle.rubyforge.org about
logging for more information on how to use and configure loggers.
- "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)@).
- "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:
* has internal state
* will be used multiple times for different situations
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.
- "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:
* guard some specific functionality
* represent state that is global across an application
- "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.
- "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.
- "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.
- "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.