needle 0.9.0 → 1.0.0

data/doc/faq/faq.yml

@@ -58,18 +58,400 @@
       singleton, singleton_deferred, etc.).
 
 - "How do I...":
-  - "create a new registry?":
-  - "register a service?":
-  - "create a namespace?":
-  - "write log messages?":
-  - "exclude methods from being intercepted?":
+  - "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@ service. 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"
+        ...
+      </pre>
+
+
+      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...":
-  - "specify a service model?":
-    - "Like, :prototype?":
-    - "Like, :prototype_deferred?":
-    - "Like, :singleton?":
-    - "Like, :singleton_deferred?":
-    - "Like, :threaded?":
-    - "Like, :threaded_deferred?":
-  - "use interceptors?":
-  - "create my own pipeline element?":
+  - "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@, @: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.

data/doc/manual-html/chapter-1.html

@@ -14,8 +14,8 @@
           </div>
         </td><td valign='middle' align='right'>
           <div class="info">
-            Needle Version: <strong>0.9.0</strong><br />
-            Manual Last Updated: <strong>2004-10-28 15:34 GMT</strong>
+            Needle Version: <strong>1.0.0</strong><br />
+            Manual Last Updated: <strong>2004-11-04 14:24 GMT</strong>
           </div>
         </td></tr>
       </table>
@@ -105,6 +105,16 @@
                 
               <ol type="1">
                 
+                  <li><a href="chapter-5.html#s1">Overview</a></li>
+                
+                  <li><a href="chapter-5.html#s2">Architecture</a></li>
+                
+                  <li><a href="chapter-5.html#s3">Attaching</a></li>
+                
+                  <li><a href="chapter-5.html#s4">Ordering</a></li>
+                
+                  <li><a href="chapter-5.html#s5">Custom</a></li>
+                
               </ol>
             </li>
           
@@ -115,6 +125,12 @@
                 
               <ol type="1">
                 
+                  <li><a href="chapter-6.html#s1">Overview</a></li>
+                
+                  <li><a href="chapter-6.html#s2">Pipelines</a></li>
+                
+                  <li><a href="chapter-6.html#s3">Models</a></li>
+                
               </ol>
             </li>
           
@@ -125,25 +141,38 @@
                 
               <ol type="1">
                 
+                  <li><a href="chapter-7.html#s1">Overview</a></li>
+                
+                  <li><a href="chapter-7.html#s2">LogFactory</a></li>
+                
+                  <li><a href="chapter-7.html#s3">Configuration</a></li>
+                
               </ol>
             </li>
           
             <li>
                 <a href="chapter-8.html">
-                Creating Libraries
+                Service Libraries
                 </a>
                 
               <ol type="1">
                 
+                  <li><a href="chapter-8.html#s1">Overview</a></li>
+                
+                  <li><a href="chapter-8.html#s2">Creating Libraries</a></li>
+                
+                  <li><a href="chapter-8.html#s3">Using Libraries</a></li>
+                
               </ol>
             </li>
           
           </ol>
 
-          <h2>API Reference</h2>
+          <h2>Other Documentation</h2>
 
           <ul>
             <li><a href="http://needle.rubyforge.org/api/index.html">Needle API</a></li>
+            <li><a href="http://needle.rubyforge.org/faq.html">Needle FAQ</a></li>
           </ul>
 
           <h2>Tutorials</h2>