needle 1.1.0 → 1.2.0

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

@@ -14,8 +14,8 @@
           </div>
         </td><td valign='middle' align='right'>
           <div class="info">
-            Needle Version: <strong>1.1.0</strong><br />
-            Manual Last Updated: <strong>2004-11-11 17:31 GMT</strong>
+            Needle Version: <strong>1.2.0</strong><br />
+            Manual Last Updated: <strong>2004-11-18 15:36 GMT</strong>
           </div>
         </td></tr>
       </table>
@@ -221,11 +221,10 @@
 
    <div class="section">
      <p>The service locator works well when there are few dependencies, and the dependency graph is not very deep. However, it has a few drawbacks:</p>
-
 	<ol>
-	<li>It requires each object to accept the locator as a parameter, and to know how to use it. This is problematic if you want to use existing classes that were created without knowledge of a locator. (I.e., <code>Logger</code>, in the Ruby library).<br />
+	<li>It requires each object to accept the locator as a parameter, and to know how to use it. This is problematic if you want to use existing classes that were created without knowledge of a locator. (I.e., <code>Logger</code>, in the Ruby library).
 </li>
-		<li>It requires each object to know what the services are named, in the locator. If you ever decide to change the name of a service in the locator, you may have to change lots of code to comply with the change.<br />
+		<li>It requires each object to know what the services are named, in the locator. If you ever decide to change the name of a service in the locator, you may have to change lots of code to comply with the change.
 </li>
 		<li>For deep dependency graphs, it can become cumbersome to have to pass the locator to each constructor.</li>
 	</ol>
@@ -245,6 +244,7 @@
    <div class="section">
      <p>Setting up for DI is very similar to the setup for a service locator, but instead of passing the locator (we&#8217;ll call it a <em>registry</em> now), we only pass (or set) the dependencies that the service itself needs.</p>
 
+
 <pre>
   require 'needle'
 
@@ -283,11 +283,9 @@
 
   ...
 </pre>
-
 	<p>The <code>create_application</code> method is now (necessarily) a little more complex, since it now contains all of the initialization logic for each service in the application. However, look how much simpler this made the other classes, especially the <code>Application</code> class.</p>
 
-	<p>Now, each class no longer even needs to care that it is being initialized via another container. All it knows is that when it is created, it will be given each of its dependencies (either as constructor parameters or as property accessors).<br />
-</p>
+	<p>Now, each class no longer even needs to care that it is being initialized via another container. All it knows is that when it is created, it will be given each of its dependencies (either as constructor parameters or as property accessors).</p>
    </div>
 
 

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

@@ -14,8 +14,8 @@
           </div>
         </td><td valign='middle' align='right'>
           <div class="info">
-            Needle Version: <strong>1.1.0</strong><br />
-            Manual Last Updated: <strong>2004-11-11 17:31 GMT</strong>
+            Needle Version: <strong>1.2.0</strong><br />
+            Manual Last Updated: <strong>2004-11-18 15:36 GMT</strong>
           </div>
         </td></tr>
       </table>
@@ -224,8 +224,7 @@
 
 	<p>Needle comes with one interceptor, the LoggingInterceptor. This allows you to easily trace the execution of your services by logging method entry and exit, as well as any exceptions that are raised.</p>
 
-	<p>You can, of course, implement your own interceptors as well.<br />
-</p>
+	<p>You can, of course, implement your own interceptors as well.</p>
    </div>
 
 
@@ -242,8 +241,7 @@
 
 	<p>The interceptors themselves are attached to the service during the execution of its instantiation pipeline (see Service Models). Thus, any action in the pipeline that is situated closer to the service than the interceptor pipeline action will bypass the interceptors altogether. This allows you to attach hooks to your service that can be called without invoking the interceptors on the service.</p>
 
-	<p>Another thing to keep in mind is that the interceptors are one-to-one for each service instance. Thus, if your service is a prototype (see the Service Models chapter), you&#8217;ll have one instance of each interceptor for each instance of your service.<br />
-</p>
+	<p>Another thing to keep in mind is that the interceptors are one-to-one for each service instance. Thus, if your service is a prototype (see the Service Models chapter), you&#8217;ll have one instance of each interceptor for each instance of your service.</p>
    </div>
 
 
@@ -266,60 +264,59 @@
 
 	<p>You can attach interceptor factories to your service using the <code>#interceptor(...).with {...}</code> syntax:</p>
 
+
 <pre>
   reg.register( :foo ) {...}
   reg.intercept( :foo ).with { MyInterceptorFactory }
 </pre>
-
 	<p>Note that you could also make the interceptor factory a service:</p>
 
+
 <pre>
   reg.register( :foo ) {...}
   reg.register( :my_interceptor ) { MyInterceptorFactory }
   reg.intercept( :foo ).with { |c| c.my_interceptor }
 </pre>
-
 	<p>And, to make accessing interceptor services even more convenient, you can use the <code>#with!</code> method (which executes its block within the context of the calling container):</p>
 
+
 <pre>
   reg.register( :foo ) {...}
   reg.register( :my_interceptor ) { MyInterceptorFactory }
   reg.intercept( :foo ).with! { my_interceptor }
 </pre>
-
 	<h3>Blocks</h3>
 
-	<p>Sometimes creating an entire class to implement an interceptor is overkill. This is particularly the case during debugging or testing, when you might want to attach an interceptor to class to verify that a parameter passed is correct, or a return value is what you expect. To satisfy these conditions, you can using the<br />
+	<p>Sometimes creating an entire class to implement an interceptor is overkill. This is particularly the case during debugging or testing, when you might want to attach an interceptor to class to verify that a parameter passed is correct, or a return value is what you expect. To satisfy these conditions, you can using the
 <code>#doing</code> method.  Just give it a block that accepts two parameters (the chain, and context) and you&#8217;re good to go!</p>
 
+
 <pre>
   reg.register( :foo ) {...}
   reg.intercept( :foo ).doing { |chain,ctx| ...; chain.process_next( ctx ) }
 </pre>
-
 	<p>Note that this approach is about 40% slower than using an interceptor factory, so it should not be used if performance is an issue.</p>
 
 	<h3>Options</h3>
 
 	<p>Some interceptors can accept configuration options. For example, the LoggingInterceptor allows clients to specify methods that should and shouldn&#8217;t be intercepted. Options are specified via the <code>#with_options</code> method.</p>
 
+
 <pre>
   reg.register( :foo ) {...}
   reg.intercept( :foo ).
     with { |c| c.logging_interceptor }.
     with_options( :exclude =&gt; [ "method1", "method2" ] )
 </pre>
-
 	<p>Options can apply to the blocks given to the <code>#doing</code> method, too. The block may access the options via the <code>#data[:options]</code> member of the context:</p>
 
+
 <pre>
   reg.intercept( :foo ).
     doing { |ch,ctx| ...; p ctx.data[:options][:value]; ... }.
     with_options( :value =&gt; "hello" )
 </pre>
-
-	<p>With blocks, of course, the value of such an approach is limited.<br />
-</p>
+	<p>With blocks, of course, the value of such an approach is limited.</p>
    </div>
 
 
@@ -338,14 +335,13 @@
 
 	<p>You can specify the priority as an option when attaching an interceptor:</p>
 
+
 <pre>
   reg.register( :foo ) { ... }
   reg.intercept( :foo ).with { Something }.with_options( :priority =&gt; 100 )
   reg.intercept( :foo ).with { SomethingElse }.with_options( :priority =&gt; 50 )
 </pre>
-
-	<p>Without the priorities, when a method of <code>:foo</code> was invoked, Something would be called first, and then SomethingElse. <em>With</em> the priorities (as specified), SomethingElse would be called before Something (since SomethingElse has a lower priority).<br />
-</p>
+	<p>Without the priorities, when a method of <code>:foo</code> was invoked, Something would be called first, and then SomethingElse. <em>With</em> the priorities (as specified), SomethingElse would be called before Something (since SomethingElse has a lower priority).</p>
    </div>
 
 
@@ -362,6 +358,7 @@
 
 	<p>An interceptor factory can be any object, as long as it implements the method <code>#new</code> with two parameters, the <em>service point</em> (service &#8220;definition&#8221;) of the service that the interceptor will be bound to, and a hash of the options that were passed to the interceptor when it was attached to the service. This method should then return a new interceptor instance, which must implement the <code>#process</code> method. The <code>#process</code> method should accept two parameters: an object representing the <em>chain</em> of interceptors, and the invocation <em>context</em>.</p>
 
+
 <pre>
   class MyInterceptorFactory
     def initialize( point, options )
@@ -377,9 +374,9 @@
     end
   end
 </pre>
-
 	<p>Once you&#8217;ve created your factory, you can attach it to a service:</p>
 
+
 <pre>
   reg.intercept( :foo ).with { MyInterceptorFactory }
 </pre>

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

@@ -14,8 +14,8 @@
           </div>
         </td><td valign='middle' align='right'>
           <div class="info">
-            Needle Version: <strong>1.1.0</strong><br />
-            Manual Last Updated: <strong>2004-11-11 17:31 GMT</strong>
+            Needle Version: <strong>1.2.0</strong><br />
+            Manual Last Updated: <strong>2004-11-18 15:36 GMT</strong>
           </div>
         </td></tr>
       </table>
@@ -222,8 +222,7 @@
    <div class="section">
      <p>Service models are the mechanism by which a client can specify how the lifecycle of a particular service should be managed. By default, all services are managed as <em>singletons</em>, but it is a simple matter to choose a different behavior when a service is registered.</p>
 
-	<p>Underneath, service models are implemented using an <em>instantiation pipeline</em>.<br />
-</p>
+	<p>Underneath, service models are implemented using an <em>instantiation pipeline</em>.</p>
    </div>
 
 
@@ -243,11 +242,11 @@
 	<h3>Standard Pipeline Elements</h3>
 
 	<p>There are five standard pipeline elements available in Needle (although you may certainly create your own):</p>
-
 	<ul>
 	<li><code>deferred</code>: this will always return a proxy that wraps subsequent pipeline elements, causing the subsequent elements to be executed only when a method is invoked on the proxy (at which point the method is then delegated to the resulting service).</li>
 		<li><code>initialize</code>: this will invoke a method on the resulting service (defaults to <code>initialize_service</code>, though it can be changed). It is used for doing final initialization of services (for services that need it).</li>
 		<li><code>interceptor</code>: this element is used to implement the proxy that wraps the interceptors around the service. It is only attached to the pipeline when an interceptor is attached to a service.</li>
+		<li><code>multiton</code>: this element enforces a multiton guard on the service. This means that the service will only be instantiated once for each unique set of parameters given to the service.</li>
 		<li><code>singleton</code>: this is a multiplicity guard that ensures a service is instantiated only once per process.</li>
 		<li><code>threaded</code>: this is like the <code>singleton</code> element, but it ensures that a service is instantiated no more than once <em>per thread</em>.</li>
 	</ul>
@@ -262,6 +261,7 @@
 
 	<p>Creating new pipeline elements simple. Just create a new class that extends <code>Needle::Pipeline::Element</code>. Set the default pipeline priority (using the <code>#set_default_priority</code> class method), and then implement the <code>#call</code> method (accepting at least two parameters: the container and the service point).</p>
 
+
 <pre>
   require 'needle/pipeline/element'
 
@@ -276,7 +276,6 @@
     end
   end
 </pre>
-
 	<p>To invoke the next element of the pipeline, just invoke <code>#succ.call(...)</code>.</p>
 
 	<p>If needed, you can also implement <code>#initialize_element</code> (with no arguments), which you may invoke to perform initialization of the element. From there, you can access the options that were given to the element via the <code>#options</code> accessor.</p>
@@ -287,16 +286,17 @@
 
 	<p>You can specify the pipeline elements to use for a service via the <code>:pipeline</code> option. This must refer to an array, each element of which must be either a symbol (in which case it references an element of the <code>:pipeline_elements</code> service), or a class (in which case it must implement the interface required by @Needle::Pipeline::Element).</p>
 
+
 <pre>
   reg.register( :foo, :pipeline =&gt; [ :singleton, MyPipelineElement ] ) { ... }
 </pre>
-
 	<p>The elements will be sorted based on their priorities, with lower priorities sorting closer to the instantiation block, and higher priorities sorting closer to the client.</p>
 
 	<h3>Making Custom Pipeline Elements Available</h3>
 
 	<p>You can make your custom pipeline elements available (so they can be referenced by symbol, instead of class name) by adding them to the <code>:pipeline_elements</code> service:</p>
 
+
 <pre>
   reg.pipeline_elements[ :my_pipeline_element ] = MyPipelineElement
   reg.register( :foo, :pipeline =&gt; [ :singleton, :my_pipeline_element ] ) { ... }
@@ -323,6 +323,26 @@
 			<th style="text-align:left;">Pipeline</th>
 			<th style="text-align:left;">Effect</th>
 		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:multiton</code></td>
+			<td style="vertical-align:top;"><code>:multiton</code></td>
+			<td>The returned value will be unique for each unique parameter set given to the service.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:multiton_deferred</code></td>
+			<td style="vertical-align:top;"><code>:multiton</code>, <code>:deferred</code></td>
+			<td>As <code>:multiton</code>, but a proxy is returned, deferring the instantiation of the service itself until a method is invoked on it.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:multiton_initialize</code></td>
+			<td style="vertical-align:top;"><code>:multiton</code>, <code>:initialize</code></td>
+			<td>As <code>:multiton</code>, but invoke an initialization method on every service instance as soon as they are created.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:multiton_deferred_initialize</code></td>
+			<td style="vertical-align:top;"><code>:multiton</code>, <code>:deferred</code>, <code>:initialize</code></td>
+			<td>As <code>:multiton</code>, but a proxy is returned, deferring the instantiation of the service itself until a method is invoked on it. When the service is instantiated, an initialization method will be invoked on it.</td>
+		</tr>
 		<tr>
 			<td style="vertical-align:top;"><code>:prototype</code></td>
 			<td style="vertical-align:top;">(empty)</td>
@@ -385,18 +405,21 @@
 		</tr>
 	</table>
 
+
+
 	<h3>Specifying a Service Model</h3>
 
 	<p>You specify the service model by passing the <code>:model</code> option when you register a service. (You must only specify <em>either</em> the model, <em>or</em> the pipeline, but not both.)</p>
 
+
 <pre>
   reg.register( :foo, :model =&gt; :singleton_deferred ) {...}
 </pre>
-
 	<h3>Defining New Models</h3>
 
 	<p>You can create your own service models by adding the corresponding pipelines to the <code>:service_models</code> service:</p>
 
+
 <pre>
   reg.service_models[ :my_service_model ] = [ :singleton, :my_pipeline_element ]
   reg.register( :foo, :model =&gt; :my_service_model ) {...}

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

@@ -14,8 +14,8 @@
           </div>
         </td><td valign='middle' align='right'>
           <div class="info">
-            Needle Version: <strong>1.1.0</strong><br />
-            Manual Last Updated: <strong>2004-11-11 17:31 GMT</strong>
+            Needle Version: <strong>1.2.0</strong><br />
+            Manual Last Updated: <strong>2004-11-18 15:36 GMT</strong>
           </div>
         </td></tr>
       </table>
@@ -224,8 +224,7 @@
 
 	<p>Needle&#8217;s logging framework is built on top of the standard Ruby <code>Logger</code> library. However, it extends that library to add additional functionality, including customizable message formats and a centralized location for obtaining logger instances.</p>
 
-	<p>This centralized location is the LogFactory.<br />
-</p>
+	<p>This centralized location is the LogFactory.</p>
    </div>
 
 
@@ -240,34 +239,43 @@
    <div class="section">
      <p>The LogFactory is available as a service, so that any component that needs a logger instance can gain easy access to one. The factory&#8217;s service name is <code>:logs</code>.</p>
 
+
 <pre>
   factory = reg.logs
 </pre>
-
 	<p>You obtain logger instances from the factory by passing a logger name to <code>#get</code>:</p>
 
+
 <pre>
   logger = reg.logs.get "a logger name" 
 </pre>
-
 	<p>Subsequent calls to <code>#get</code> will return the same logger instance for the given logger name.</p>
 
 	<h3>Loggers for Services</h3>
 
 	<p>Typically, you&#8217;ll use this to assign a logger instance to a service when it is constructed. In that case, the name of the logger is the fully-qualified name of the service:</p>
 
+
 <pre>
   reg.register( :foo ) do |c,p|
     Foo.new( c.logs.get( p.fullname ) )
   end
 </pre>
-
 	<p>As a convenience, if the value passed to <code>#get</code> responds to either <code>fullname</code> or <code>name</code>, the return value of that message will be used as the name. Thus, you can do the following:</p>
 
+
 <pre>
   reg.register( :foo ) do |c,p|
     Foo.new( c.logs.get( p ) )
   end
+</pre>
+	<p>As a further convenience, there is a <code>:log_for</code> service that is parameterized. Just pass the name of the log to retreive (or the service point instance) and it will return the log handle directly:</p>
+
+
+<pre>
+  reg.register( :foo ) do |c,p|
+    Foo.new( c.log_for( p ) )
+  end
 </pre>
    </div>
 
@@ -322,8 +330,11 @@
 		</tr>
 	</table>
 
+
+
 	<p>By default, the filename is &#8221;./needle.log&#8221;, and the roll_size is one megabyte. The default level is <code>:debug</code>. If you wanted to specify a different filename and default level of <code>:warn</code>, you could do:</p>
 
+
 <pre>
   reg = Needle::Registry.new(
     :logs =&gt; {
@@ -331,9 +342,9 @@
       :default_level =&gt; :warn }
   )
 </pre>
-
 	<p>Alternatively, you can easily put the logging configuration in a <span class="caps">YAML</span> file and read it in, like so:</p>
 
+
 <pre>
   require 'yaml'
   reg = Needle::Registry.new(

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

@@ -14,8 +14,8 @@
           </div>
         </td><td valign='middle' align='right'>
           <div class="info">
-            Needle Version: <strong>1.1.0</strong><br />
-            Manual Last Updated: <strong>2004-11-11 17:31 GMT</strong>
+            Needle Version: <strong>1.2.0</strong><br />
+            Manual Last Updated: <strong>2004-11-18 15:36 GMT</strong>
           </div>
         </td></tr>
       </table>
@@ -222,8 +222,7 @@
    <div class="section">
      <p>Using Needle as it has been presented so far works fine when you are dealing with a single application, all self-encapsulated. When you start dealing with combining multiple libraries, each potentially written by a different author, into a single registry, things get a little more complicated.</p>
 
-	<p>Needle provides a way for service authors to share their services. All it requires is that authors centralize their service configuration.<br />
-</p>
+	<p>Needle provides a way for service authors to share their services. All it requires is that authors centralize their service configuration.</p>
    </div>
 
 
@@ -240,6 +239,7 @@
 
 	<p>For example, if I had a library of cryptographic routines and I wanted to make them accessible as Needle services, I would create a module to contain the service definitions. Typically, this module will be defined in a file called &#8220;services.rb&#8221;, although you can certainly name it whatever you like.</p>
 
+
 <pre>
   module Crypto
 
@@ -262,11 +262,9 @@
 
   end
 </pre>
-
 	<p>Notice that there are no explicit dependencies on Needle, only on the interfaces Needle publishes. Thus, third-parties can add service configuration modules to their libraries without introducing dependencies on Needle.</p>
 
-	<p>Once a service library has been created, it can then be accessed from another library or application that wishes to import those services.<br />
-</p>
+	<p>Once a service library has been created, it can then be accessed from another library or application that wishes to import those services.</p>
    </div>
 
 
@@ -281,6 +279,7 @@
    <div class="section">
      <p>Using the libraries is as simple as requiring the file that has the service definitions, and then invoking the <code>#register_services</code> module function:</p>
 
+
 <pre>
   require 'needle'
 
@@ -294,9 +293,9 @@
 
   prng = reg.crypto.prng
 </pre>
-
 	<p>To make this easier, the Container class has a convenience method named <code>#require</code>:</p>
 
+
 <pre>
   require 'needle'
 
@@ -308,9 +307,7 @@
 
   prng = reg.crypto.prng
 </pre>
-
-	<p>The <code>Container#require</code> method will require the file, and then look for a <code>#register_services</code> method of the named module. It will execute that method, passing the container as an argument.<br />
-</p>
+	<p>The <code>Container#require</code> method will require the file, and then look for a <code>#register_services</code> method of the named module. It will execute that method, passing the container as an argument.</p>
    </div>