needle 0.9.0 → 1.0.0

data/doc/manual-html/chapter-6.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 @@
                 </strong> <big>&larr;</big>
               <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,199 @@
 
 
 
+     <h2>
+       <a name="s1"></a>
+       6.1. Overview
+     </h2>
+
+   
+
+   <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>
+   </div>
+
+
+
+     <h2>
+       <a name="s2"></a>
+       6.2. Pipelines
+     </h2>
+
+   
+
+   <div class="section">
+     <p>An <em>instantiation pipeline</em> is a sequence of elements, each of which knows how to perform some aspect of the instantiation of a service.</p>
+
+	<p>Every service consists of at least one instantiation element&#8212;the block that was given when the service was registered. Other elements may be combined with this block to enforce various aspects of lifecycle management, such as <em>multiplicity</em> (singleton vs. prototype) and <em>laziness</em> (deferred vs. immediate instantiation).</p>
+
+	<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>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>
+
+	<h3>Priorities</h3>
+
+	<p>Just like interceptors, pipeline elements have priorities as well. These priorities determine the order in which the elements are executed in the pipeline.</p>
+
+	<p>Each element type has a default priority, although that priority can be overridden when the element is added to the pipeline.</p>
+
+	<h3>Custom Pipeline Elements</h3>
+
+	<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'
+
+  class MyPipelineElement &lt; Needle::Pipeline::Element
+    set_default_priority 50
+
+    def call( container, point, *args )
+      ...
+      result = succ.call( container, point, *args )
+      ...
+      return result
+    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>
+
+	<p>See the implementations of the existing elements in <code>needle/lifecycle</code> for examples.</p>
+
+	<h3>Added Pipelines Elements to Services</h3>
+
+	<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 ] ) { ... }
+</pre>
+   </div>
+
+
+
+     <h2>
+       <a name="s3"></a>
+       6.3. Models
+     </h2>
+
+   
+
+   <div class="section">
+     <p>Specifying an entire pipeline for every service point can be tedious. For that reason, there are <em>service models</em>. A service model is a kind of template that names a pre-configured sequence of pipeline elements. Needle comes preconfigured with many service models.</p>
+
+	<h3>Standard Service Models:</h3>
+
+	<table style="border: 1px solid black;">
+		<tr>
+			<th style="text-align:left;">Name</th>
+			<th style="text-align:left;">Pipeline</th>
+			<th style="text-align:left;">Effect</th>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:prototype</code></td>
+			<td style="vertical-align:top;">(empty)</td>
+			<td>Immediately instantiate the service, at every request.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:prorotype_deferred</code></td>
+			<td style="vertical-align:top;"><code>:deferred</code></td>
+			<td>Return a proxy, that will instantiate the service the first time a method is invoked on the proxy. A new proxy instance will be returned for each request.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:prototype_initialize</code></td>
+			<td style="vertical-align:top;"><code>:initialize</code></td>
+			<td>Immediately instantiate the service, and invoke an initialization method, at every request.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:prototype_deferred_initialize</code></td>
+			<td style="vertical-align:top;"><code>:deferred</code>, <code>:initialize</code></td>
+			<td>Return a proxy, that will instantiate the service and invoke an initialization method the first time a method is invoked on the proxy. A new proxy instance will be returned for each request.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:singleton</code></td>
+			<td style="vertical-align:top;"><code>:singleton</code></td>
+			<td>Immediately instantiate the service the first time it is requested, returning a cached instance subsequently.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:singleton_deferred</code></td>
+			<td style="vertical-align:top;"><code>:singleton</code>, <code>:deferred</code></td>
+			<td>Return a proxy that will instantiate the service the first time a method is requested on the proxy. Subsequent requests for this service will return the same proxy instance.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:singleton_initialize</code></td>
+			<td style="vertical-align:top;"><code>:singleton</code>, <code>:initialize</code></td>
+			<td>Immediately instantiate a service and invoke an initialization method on it. Subsequent requests for this service will return a cached instance.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:singleton_deferred_initialize</code></td>
+			<td style="vertical-align:top;"><code>:singleton</code>, <code>:deferred</code>, <code>:initialize</code></td>
+			<td>Return a proxy that will instantiate the service and invoke an initialization method on it the first time a method is requested on the proxy. Subsequent requests for this service will return the same proxy instance.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:threaded</code></td>
+			<td style="vertical-align:top;"><code>:threaded</code></td>
+			<td>Immediately instantiate the service the first time it is requested from the current thread, returning a cached instance for every subsequent request from the same thread.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:threaded_deferred</code></td>
+			<td style="vertical-align:top;"><code>:threaded</code>, <code>:deferred</code></td>
+			<td>Return a proxy object that will instantiate the service the first time a method is invoked on the proxy. Subsequent requests for this service from a given thread will return the thread&#8217;s cached instance.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:threaded_initialize</code></td>
+			<td style="vertical-align:top;"><code>:threaded</code>, <code>:initialize</code></td>
+			<td>Immediately instantiate the service the first time it is requested from the current thread and invoke an initialization method on it. Subsequent requests for this service from the same thread will return the cached instance.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:threaded_deferred_initialize</code></td>
+			<td style="vertical-align:top;"><code>:threaded</code>, <code>:deferred</code>, <code>:initialize</code></td>
+			<td>Return a proxy object that will instantiate the service and invoke an initialization method on it the first time a method is invoked on the proxy. Subsequent requests for this service from a given thread will return the thread&#8217;s cached instance.</td>
+		</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 ) {...}
+</pre>
+   </div>
+
+
+
 
         </div>
 

data/doc/manual-html/chapter-7.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 @@
                 </strong> <big>&larr;</big>
               <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,138 @@
 
 
 
+     <h2>
+       <a name="s1"></a>
+       7.1. Overview
+     </h2>
+
+   
+
+   <div class="section">
+     <p>Logging is a pretty common activity in many applications. Because it is so common, Needle provides a powerful framework for logging messages in a consistent manner.</p>
+
+	<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>
+   </div>
+
+
+
+     <h2>
+       <a name="s2"></a>
+       7.2. LogFactory
+     </h2>
+
+   
+
+   <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>
+   </div>
+
+
+
+     <h2>
+       <a name="s3"></a>
+       7.3. Configuration
+     </h2>
+
+   
+
+   <div class="section">
+     <p>You can configure the LogFactory when you create the registry by passing a hash as the <code>:logs</code> option to <code>Registry.new</code>. The hash may have the following properties:</p>
+
+	<table>
+		<tr>
+			<td style="vertical-align:top;"><code>:device</code></td>
+			<td>Should refer to an IO or pseudo-IO object that will receive <code>#write</code> and <code>#close</code> messages.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:filename</code></td>
+			<td>The name of the file to write log messages to.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:roll_age</code></td>
+			<td>The number of days before the log should be rolled.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:roll_frequency</code></td>
+			<td>Either &#8216;daily&#8217;, &#8216;weekly&#8217;, or &#8216;monthly&#8217;, indicating how often the log should be rolled.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:roll_size</code></td>
+			<td>The maximum size that a log file may grow to before it is rolled.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:default_date_format</code></td>
+			<td>A <code>strftime</code>-formatted string to use for formatting message dates and times.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:default_message_format</code></td>
+			<td>A printf-styled format string to use when formatting messages. It&#8217;s format is reminiscent of Log4r, but differs in some options. See the <span class="caps">API</span> documentation for Needle::Logger for details.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:default_level</code></td>
+			<td>One of <code>:debug</code>, <code>:info</code>, <code>:warn</code>, <code>:error</code>, or <code>:fatal</code>, indicating the default level of logging detail to use.</td>
+		</tr>
+		<tr>
+			<td style="vertical-align:top;"><code>:levels</code></td>
+			<td>Another hash of pattern/level or pattern/hash pairs, where the pattern is a string describing the logger name (or names) that it matches. If the corresponding value of a key is a symbol or a string, then it describes the logging level to use for loggers that match it. If the value is a hash, then it may contain <code>:level</code>, <code>:date_format</code>, or <code>:message_format</code> keys that apply to matching logs.</td>
+		</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; {
+      :filename =&gt; "./my-app.log",
+      :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(
+    :logs =&gt; YAML.load( File.read( "log-conf.yml" ) )
+  )
+</pre>
+   </div>
+
+
+
 
         </div>