diff options
Diffstat (limited to 'test/scanners/yaml/faq.in.yml')
-rw-r--r-- | test/scanners/yaml/faq.in.yml | 492 |
1 files changed, 0 insertions, 492 deletions
diff --git a/test/scanners/yaml/faq.in.yml b/test/scanners/yaml/faq.in.yml deleted file mode 100644 index bcd8438..0000000 --- a/test/scanners/yaml/faq.in.yml +++ /dev/null @@ -1,492 +0,0 @@ ---- -- "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. - - - <pre> - reg = Needle::Registry.new - </pre> - - - 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: - - - <pre> - reg = Needle::Registry.new do |r| - ... - end - </pre> - - - There are two other factory methods you can use for creating a Registry - instance. Both require a block. - - - <pre> - r1 = Needle::Registry.define do |builder| - ... - end - - r2 = Needle::Registry.define! do - ... - end - </pre> - - - 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): - - - <pre> - reg.register( :foo ) { Foo.new } - </pre> - - - 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"): - - - <pre> - reg.register( :foo ) do |container,point| - Foo.new( container[:bar], point.fullname ) - end - </pre> - - - 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. - - - <pre> - 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 - </pre> - - - 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: - - - <pre> - reg.define.foo { ... } - </pre> - - - Lastly, you can get the builder directly and add services using it: - - - <pre> - builder = reg.builder - builder.baz { ... } - builder.bar { ... } - </pre> - - - (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#[]: - - - <pre> - svc = registry[:foo] - svc.do_something_interesting - </pre> - - - A more convenient (but slightly more peril-fraught) approach is to send - the name of the method to the registry as a message: - - - <pre> - svc = registry.foo - </pre> - - - 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: - - - <pre> - registry.register( :hash ) { "hello, world" } - p registry.hash - </pre> - - - 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: - - - <pre> - registry.register( :foo, :model => :prototype ) {...} - registry.define.bar( :model => :threaded ) {...} - registry.define! do - baz( :model => :singleton_deferred ) {...} - ... - end - ... - </pre> - - - "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: - - - <pre> - registry.namespace( :stuff ) - </pre> - - - 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: - - - <pre> - registry.namespace( :stuff ) do |ns| - ns.register( :foo ) {...} - ns.define.bar {...} - ns.define! do - baz {...} - buf {...} - end - end - </pre> - - Because it is so common to immediately define services on the new - namespace, there are some convenience methods to make this more... - convenient. - - - <pre> - registry.namespace_define!( :stuff ) do - foo {...} - bar {...} - baz {...} - end - - registry.namespace_define( :more_stuff ) do |b| - b.blah {...} - b.argh {...} - b.hack {...} - end - </pre> - - - 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. - - - <pre> - 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" ) - ... - </pre> - - - 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. - - - <pre> - registry.register( :foo ) { ... } - registry.intercept( :foo ).with { |r| r.logging_interceptor } - - foo.something - foo.another_method( 1, 2, 3 ) - </pre> - - - 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: - - - <pre> - registry.register( :foo ) { ... } - registry.intercept( :foo ). - with { |r| r.logging_interceptor }. - with_options :exclude => [ 'foo', 'bar(>4)', '*(<2)' ] - </pre> - - - 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: - - - <pre> - 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 - </pre> - - - 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: - - - <pre> - module A - module B - def register_services( container ) - ... - end - module_function :register_services - end - end - </pre> - - - 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@. - - - <pre> - require 'a/b' - A::B.register_services( container ) - - # or - - container.require( 'a/b', "A::B" ) - </pre> - - - The definition context (i.e., the "builder" object) also supports the - require method, so you can do: - - - <pre> - container.define do |b| - b.require "a/b", "A::B" - b.foo { ... } - ... - end - </pre> - -- "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. |