needle 0.9.0 → 1.0.0

data/doc/manual-html/chapter-2.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>
@@ -351,10 +380,19 @@
   end
 </pre>
 
-	<p>And, to mirror the <code>namespace</code> method, there is also a <code>namespace!</code> method. This method creates a new namespace and then does a <code>define!</code> call on that namespace.</p>
+	<p>If you prefer the <code>define</code> approach to registering services, you may like <code>namespace_define</code>, which creates the new namespace and immediately calls <code>define</code> on it:</p>
+
+<pre>
+  registry.namespace_define :stuff do |b|
+    b.foo { Bar.new }
+    ...
+  end
+</pre>
+
+	<p>And, to mirror the <code>namespace_define</code> method, there is also a <code>namespace_define!</code> method. This method creates a new namespace and then does a <code>define!</code> call on that namespace.</p>
 
 <pre>
-  registry.namespace! :stuff do
+  registry.namespace_define! :stuff do
     foo { Bar.new }
     ...
   end

data/doc/manual-html/chapter-3.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>
@@ -188,7 +217,7 @@
 		<li><code>Application</code>. The controller that ties it all together.</li>
 	</ul>
 
-	<p>(Of course, a <em>real</em> online forum application would be significantly more complex, but the above components will do for our puroses.)</p>
+	<p>(Of course, a <em>real</em> online forum application would be significantly more complex, but the above components will do for our purposes.)</p>
 
 	<p>The dependencies between these components are:</p>
 

data/doc/manual-html/chapter-4.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>

data/doc/manual-html/chapter-5.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 @@
                 </strong> <big>&larr;</big>
               <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>
@@ -167,6 +196,181 @@
 
 
 
+     <h2>
+       <a name="s1"></a>
+       5.1. Overview
+     </h2>
+
+   
+
+   <div class="section">
+     <p>Interceptors are objects (or blocks) that sit between a client and a service and <em>intercept</em> messages (methods) sent to the service. Each service may have many such interceptors. When control is passed to an interceptor, it may then do something before and after passing control to the next interceptor, possibly even returning instead of passing control. This allows for some simple <acronym title="Aspect-Oriented Programming">AOP</acronym>-like hooks to be placed on your services.</p>
+
+	<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>
+   </div>
+
+
+
+     <h2>
+       <a name="s2"></a>
+       5.2. Architecture
+     </h2>
+
+   
+
+   <div class="section">
+     <p>Interceptors are implemented as proxy objects that front the requested service. Thus, if you request a service that has 3 interceptors wrapped around it, you&#8217;re really getting a proxy object back that will invoke the interceptors (in order) before the requested method of the service is invoked.</p>
+
+	<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>
+   </div>
+
+
+
+     <h2>
+       <a name="s3"></a>
+       5.3. Attaching
+     </h2>
+
+   
+
+   <div class="section">
+     <p>There are two ways to attach interceptors to your services. The first is to implement an interceptor <em>factory</em> that returns new interceptor <em>instances</em>, and attach the factory to your service. The second is to specify a block that implements the required functionality. Both have their uses.</p>
+
+	<h3>Interceptor Factories</h3>
+
+	<p>Interceptor factories are useful in situations where you want to implement some functionality and have it apply to multiple services. Interceptors from factories are also faster (less overhead) than interceptors from blocks, and so might be appropriate where performance is an issue.</p>
+
+	<p>An example is the LoggingInterceptor that ships with Needle. Because it is functionality that could be used on any number of services, it is implemented as a factory.</p>
+
+	<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 />
+<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>
+   </div>
+
+
+
+     <h2>
+       <a name="s4"></a>
+       5.4. Ordering
+     </h2>
+
+   
+
+   <div class="section">
+     <p>As was mentioned, a service may have multiple interceptors attached to it. By default, a method will be filtered by the interceptors in the same order that they were attached, with the first interceptor that was attached being the first one to intercept every method call.</p>
+
+	<p>You can specify a different ordering of the interceptors by giving each one a <em>priority</em>. The priority is a number, where interceptors with a higher priority sort <em>closer</em> to the service, and those with lower priorities sort <em>further</em> from the service.</p>
+
+	<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>
+   </div>
+
+
+
+     <h2>
+       <a name="s5"></a>
+       5.5. Custom
+     </h2>
+
+   
+
+   <div class="section">
+     <p>Creating your own interceptors is very easy. As was demonstrated earlier, you can always use blocks to implement an interceptor. However, for more complex interceptors, or for interceptors that you want to reuse across multiple services, you can also implement your own interceptor <em>factories</em>.</p>
+
+	<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 )
+      ...
+    end
+
+    def process( chain, context )
+      # context.sym   : the name of the method that was invoked
+      # context.args  : the array of arguments passed to the method
+      # context.block : the block passed to the method, if any
+      # context.data  : a hash that may be used to share data between interceptors
+      return context.process_next( context )
+    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>
+   </div>
+
+
+
 
         </div>