needle 0.9.0 → 1.0.0

data/doc/manual/parts/interceptors_custom.txt

@@ -0,0 +1,25 @@
+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 _factories_.
+
+An interceptor factory can be any object, as long as it implements the method @#new@ with two parameters, the _service point_ (service "definition") 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 @#process@ method. The @#process@ method should accept two parameters: an object representing the _chain_ of interceptors, and the invocation _context_.
+
+<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>
+
+Once you've created your factory, you can attach it to a service:
+
+<pre>
+  reg.intercept( :foo ).with { MyInterceptorFactory }
+</pre>

data/doc/manual/parts/interceptors_ordering.txt

@@ -0,0 +1,13 @@
+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.
+
+You can specify a different ordering of the interceptors by giving each one a _priority_. The priority is a number, where interceptors with a higher priority sort _closer_ to the service, and those with lower priorities sort _further_ from the service.
+
+You can specify the priority as an option when attaching an interceptor:
+
+<pre>
+  reg.register( :foo ) { ... }
+  reg.intercept( :foo ).with { Something }.with_options( :priority => 100 )
+  reg.intercept( :foo ).with { SomethingElse }.with_options( :priority => 50 )
+</pre>
+
+Without the priorities, when a method of @:foo@ was invoked, Something would be called first, and then SomethingElse. _With_ the priorities (as specified), SomethingElse would be called before Something (since SomethingElse has a lower priority).

data/doc/manual/parts/interceptors_overview.txt

@@ -0,0 +1,5 @@
+Interceptors are objects (or blocks) that sit between a client and a service and _intercept_ 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 AOP(Aspect-Oriented Programming)-like hooks to be placed on your services.
+
+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.
+
+You can, of course, implement your own interceptors as well.

data/doc/manual/parts/libraries_creating.txt

@@ -0,0 +1,30 @@
+This centralization is implemented by creating a module for each library you want to have services for. That module should then define a module function called (by default) @register_services@. This function should accept a single parameter--the Needle container that the services will be added to.
+
+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 "services.rb", although you can certainly name it whatever you like.
+
+<pre>
+  module Crypto
+    
+    def register_services( container )
+      container.namespace_define( :crypto ) do |b|
+        b.prng do
+          require 'crypto/prng'
+          PRNG.new
+        end
+
+        b.des do
+          require 'crypto/des'
+          DES.new
+        end
+
+        ...
+      end
+    end
+    module_function :register_services
+
+  end
+</pre>
+
+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.
+
+Once a service library has been created, it can then be accessed from another library or application that wishes to import those services.

data/doc/manual/parts/libraries_overview.txt

@@ -0,0 +1,3 @@
+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.
+
+Needle provides a way for service authors to share their services. All it requires is that authors centralize their service configuration.

data/doc/manual/parts/libraries_using.txt

@@ -0,0 +1,31 @@
+Using the libraries is as simple as requiring the file that has the service definitions, and then invoking the @#register_services@ module function:
+
+<pre>
+  require 'needle'
+
+  reg = Needle::Registry.new
+  reg.define do |b|
+    b.foo { Foo.new }
+
+    require 'crypto/services'
+    Crypto.register_services( reg )
+  end
+
+  prng = reg.crypto.prng
+</pre>
+
+To make this easier, the Container class has a convenience method named @#require@:
+
+<pre>
+  require 'needle'
+
+  reg = Needle::Registry.new
+  reg.define do |b|
+    b.foo { Foo.new }
+    b.require 'crypto/services', "Crypto"
+  end
+
+  prng = reg.crypto.prng
+</pre>
+
+The @Container#require@ method will require the file, and then look for a @#register_services@ method of the named module. It will execute that method, passing the container as an argument.

data/doc/manual/parts/logging_configuration.txt

@@ -0,0 +1,30 @@
+You can configure the LogFactory when you create the registry by passing a hash as the @:logs@ option to @Registry.new@. The hash may have the following properties:
+
+|^. @:device@|Should refer to an IO or pseudo-IO object that will receive @#write@ and @#close@ messages.|
+|^. @:filename@|The name of the file to write log messages to.|
+|^. @:roll_age@|The number of days before the log should be rolled.|
+|^. @:roll_frequency@|Either 'daily', 'weekly', or 'monthly', indicating how often the log should be rolled.|
+|^. @:roll_size@|The maximum size that a log file may grow to before it is rolled.|
+|^. @:default_date_format@|A @strftime@-formatted string to use for formatting message dates and times.|
+|^. @:default_message_format@|A printf-styled format string to use when formatting messages. It's format is reminiscent of Log4r, but differs in some options. See the API documentation for Needle::Logger for details.|
+|^. @:default_level@|One of @:debug@, @:info@, @:warn@, @:error@, or @:fatal@, indicating the default level of logging detail to use.|
+|^. @:levels@|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 @:level@, @:date_format@, or @:message_format@ keys that apply to matching logs.|
+
+By default, the filename is "./needle.log", and the roll_size is one megabyte. The default level is @:debug@. If you wanted to specify a different filename and default level of @:warn@, you could do:
+
+<pre>
+  reg = Needle::Registry.new(
+    :logs => {
+      :filename => "./my-app.log",
+      :default_level => :warn }
+  )
+</pre>
+
+Alternatively, you can easily put the logging configuration in a YAML file and read it in, like so:
+
+<pre>
+  require 'yaml'
+  reg = Needle::Registry.new(
+    :logs => YAML.load( File.read( "log-conf.yml" ) )
+  )
+</pre>

data/doc/manual/parts/logging_logfactory.txt

@@ -0,0 +1,31 @@
+The LogFactory is available as a service, so that any component that needs a logger instance can gain easy access to one. The factory's service name is @:logs@.
+
+<pre>
+  factory = reg.logs
+</pre>
+
+You obtain logger instances from the factory by passing a logger name to @#get@:
+
+<pre>
+  logger = reg.logs.get "a logger name"
+</pre>
+
+Subsequent calls to @#get@ will return the same logger instance for the given logger name.
+
+h3. Loggers for Services
+
+Typically, you'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:
+
+<pre>
+  reg.register( :foo ) do |c,p|
+    Foo.new( c.logs.get( p.fullname ) )
+  end
+</pre>
+
+As a convenience, if the value passed to @#get@ responds to either @fullname@ or @name@, the return value of that message will be used as the name. Thus, you can do the following:
+
+<pre>
+  reg.register( :foo ) do |c,p|
+    Foo.new( c.logs.get( p ) )
+  end
+</pre>

data/doc/manual/parts/logging_overview.txt

@@ -0,0 +1,5 @@
+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.
+
+Needle's logging framework is built on top of the standard Ruby @Logger@ library. However, it extends that library to add additional functionality, including customizable message formats and a centralized location for obtaining logger instances.
+
+This centralized location is the LogFactory.

data/doc/manual/parts/models_models.txt

@@ -0,0 +1,35 @@
+Specifying an entire pipeline for every service point can be tedious. For that reason, there are _service models_. A service model is a kind of template that names a pre-configured sequence of pipeline elements. Needle comes preconfigured with many service models.
+
+h3. Standard Service Models:
+
+table{border: 1px solid black}.
+|_<. Name|_<. Pipeline|_<. Effect|
+|^. @:prototype@|^. (empty)|Immediately instantiate the service, at every request.|
+|^. @:prorotype_deferred@|^. @:deferred@|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.|
+|^. @:prototype_initialize@|^. @:initialize@|Immediately instantiate the service, and invoke an initialization method, at every request.|
+|^. @:prototype_deferred_initialize@|^. @:deferred@, @:initialize@|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.|
+|^. @:singleton@|^. @:singleton@|Immediately instantiate the service the first time it is requested, returning a cached instance subsequently.|
+|^. @:singleton_deferred@|^. @:singleton@, @:deferred@|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.|
+|^. @:singleton_initialize@|^. @:singleton@, @:initialize@|Immediately instantiate a service and invoke an initialization method on it. Subsequent requests for this service will return a cached instance.|
+|^. @:singleton_deferred_initialize@|^. @:singleton@, @:deferred@, @:initialize@|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.|
+|^. @:threaded@|^. @:threaded@|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.|
+|^. @:threaded_deferred@|^. @:threaded@, @:deferred@|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's cached instance.|
+|^. @:threaded_initialize@|^. @:threaded@, @:initialize@|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.|
+|^. @:threaded_deferred_initialize@|^. @:threaded@, @:deferred@, @:initialize@|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's cached instance.|
+
+h3. Specifying a Service Model
+
+You specify the service model by passing the @:model@ option when you register a service. (You must only specify _either_ the model, _or_ the pipeline, but not both.)
+
+<pre>
+  reg.register( :foo, :model => :singleton_deferred ) {...}
+</pre>
+
+h3. Defining New Models
+
+You can create your own service models by adding the corresponding pipelines to the @:service_models@ service:
+
+<pre>
+  reg.service_models[ :my_service_model ] = [ :singleton, :my_pipeline_element ]
+  reg.register( :foo, :model => :my_service_model ) {...}
+</pre>

data/doc/manual/parts/models_overview.txt

@@ -0,0 +1,3 @@
+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 _singletons_, but it is a simple matter to choose a different behavior when a service is registered.
+
+Underneath, service models are implemented using an _instantiation pipeline_.

data/doc/manual/parts/models_pipelines.txt

@@ -0,0 +1,63 @@
+An _instantiation pipeline_ is a sequence of elements, each of which knows how to perform some aspect of the instantiation of a service.
+
+Every service consists of at least one instantiation element--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 _multiplicity_ (singleton vs. prototype) and _laziness_ (deferred vs. immediate instantiation).
+
+h3. Standard Pipeline Elements
+
+There are five standard pipeline elements available in Needle (although you may certainly create your own):
+
+* @deferred@: 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).
+* @initialize@: this will invoke a method on the resulting service (defaults to @initialize_service@, though it can be changed). It is used for doing final initialization of services (for services that need it).
+* @interceptor@: 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.
+* @singleton@: this is a multiplicity guard that ensures a service is instantiated only once per process.
+* @threaded@: this is like the @singleton@ element, but it ensures that a service is instantiated no more than once _per thread_.
+
+h3. Priorities
+
+Just like interceptors, pipeline elements have priorities as well. These priorities determine the order in which the elements are executed in the pipeline.
+
+Each element type has a default priority, although that priority can be overridden when the element is added to the pipeline.
+
+h3. Custom Pipeline Elements
+
+Creating new pipeline elements simple. Just create a new class that extends @Needle::Pipeline::Element@. Set the default pipeline priority (using the @#set_default_priority@ class method), and then implement the @#call@ method (accepting at least two parameters: the container and the service point).
+
+<pre>
+  require 'needle/pipeline/element'
+
+  class MyPipelineElement < Needle::Pipeline::Element
+    set_default_priority 50
+    
+    def call( container, point, *args )
+      ...
+      result = succ.call( container, point, *args )
+      ...
+      return result
+    end
+  end
+</pre>
+
+To invoke the next element of the pipeline, just invoke @#succ.call(...)@.
+
+If needed, you can also implement @#initialize_element@ (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 @#options@ accessor.
+
+See the implementations of the existing elements in @needle/lifecycle@ for examples.
+
+h3. Added Pipelines Elements to Services
+
+You can specify the pipeline elements to use for a service via the @:pipeline@ 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 @:pipeline_elements@ service), or a class (in which case it must implement the interface required by @Needle::Pipeline::Element).
+
+<pre>
+  reg.register( :foo, :pipeline => [ :singleton, MyPipelineElement ] ) { ... }
+</pre>
+
+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.
+
+h3. Making Custom Pipeline Elements Available
+
+You can make your custom pipeline elements available (so they can be referenced by symbol, instead of class name) by adding them to the @:pipeline_elements@ service:
+
+<pre>
+  reg.pipeline_elements[ :my_pipeline_element ] = MyPipelineElement
+  reg.register( :foo, :pipeline => [ :singleton, :my_pipeline_element ] ) { ... }
+</pre>

data/lib/needle/container.rb

@@ -68,16 +68,25 @@ module Needle
         @container.namespace( *parms, &block )
       end
 
-      # Delegate to Container#namespace!.
-      def namespace!( *parms, &block )
-        @container.namespace!( *parms, &block )
+      # Delegate to Container#namespace_define!.
+      def namespace_define!( *parms, &block )
+        @container.namespace_define!( *parms, &block )
       end
 
+      alias :namespace! :namespace_define!
+
       # Delegate to Container#define on the new namespace.
       def namespace_define( *parms, &block )
         @container.namespace( *parms ) { |ns| ns.define( &block ) }
       end
 
+      # Delegate to Container#require on the current container.
+      def require( *parms )
+        # this is necessary to work around an rdoc bug...rdoc doesn't like
+        # calling require with a variable number of arguments.
+        @container.__send__( :require, *parms )
+      end
+
       # Any method invocation with no block and no parameters is interpreted to
       # be a service reference on the wrapped container, and delegates to
       # Container#[]. If the block is not given but the args are not empty, a
@@ -202,7 +211,7 @@ module Needle
     # by Container.  The two statements are really identical:
     #
     #   container.namespace( :calc )
-    #   container.register( :calc ) { |c| Needle::Container.new( c, :calc ) }
+    #   container.register( :calc ) { |c,p| Needle::Container.new( c, p.name ) }
     #
     # Note that this means that namespaces may be singletons or prototypes, or
     # have immediate or deferred instantiation, and so forth. (The default of
@@ -238,7 +247,7 @@ module Needle
     # by Container.  The two statements are really identical:
     #
     #   container.namespace( :calc )
-    #   container.register( :calc ) { |c| Needle::Container.new( c, :calc ) }
+    #   container.register( :calc ) { |c,p| Needle::Container.new( c, p.name ) }
     #
     # Note that this means that namespaces may be singletons or prototypes, or
     # have immediate or deferred instantiation, and so forth. (The default of
@@ -275,7 +284,7 @@ module Needle
     # by Container.  The two statements are really identical:
     #
     #   container.namespace( :calc )
-    #   container.register( :calc ) { |c| Needle::Container.new( c, :calc ) }
+    #   container.register( :calc ) { |c,p| Needle::Container.new( c, p.name ) }
     #
     # Note that this means that namespaces may be singletons or prototypes, or
     # have immediate or deferred instantiation, and so forth. (The default of
@@ -284,7 +293,7 @@ module Needle
     #
     # Usage:
     #
-    #   container.define_namespace( :operations ) do |b|
+    #   container.namespace_define( :operations ) do |b|
     #     b.add { Adder.new }
     #     ...
     #   end
@@ -374,6 +383,42 @@ module Needle
       @service_points.keys
     end
 
+    # Require the given file, and then invoke the given registration method on
+    # the target module. The container will be passed as the sole parameter to
+    # the registration method. This allows you to easily decentralize the
+    # definition of services.
+    #
+    # Usage:
+    #
+    #   container.require( "app/services", "App::Services" )
+    #
+    #   # in app/services.rb:
+    #
+    #   module App
+    #     module Services
+    #
+    #       def register_services( container )
+    #         ...
+    #       end
+    #       module_function :register_services
+    #
+    #     end
+    #   end
+    def require( file, target_name, registration_method=:register_services )
+      Kernel.require file
+
+      if target_name.is_a?( Module )
+        target = target_name
+      else
+        target = Object
+        target_name.to_s.split( /::/ ).each do |element|
+          target = target.const_get( element )
+        end
+      end
+
+      target.__send__( registration_method, self )
+    end
+
     # As a convenience for accessing services, this delegates any message
     # sent to the container (which has no parameters and no block) to
     # Container#[]. Note that this incurs slightly more overhead than simply

data/lib/needle/lifecycle/initialize.rb

@@ -25,7 +25,7 @@ module Needle
     # (hence, the low default priority).
     class Initialize < Needle::Pipeline::Element
 
-      set_default_priority -100
+      set_default_priority( -100 )
 
       # Initialize the element. Looks at the options hash to determine the
       # name of the initialization method to call, defaulting to

data/lib/needle/log-factory.rb

@@ -14,6 +14,7 @@
 # =============================================================================
 #++
 
+require 'needle/errors'
 require 'needle/logger'
 require 'thread'
 
@@ -52,6 +53,12 @@ module Needle
     # The device that logs will write to.
     attr_reader :device
 
+    VALID_OPTIONS = [ :device, :filename, :roll_age, :roll_frequency,
+                      :roll_size, :default_date_format,
+                      :default_message_format, :default_level, :levels ]
+
+    VALID_LEVEL_OPTIONS = [ :level, :date_format, :message_format ]
+                      
     # Create a new LogFactory using the given initialization parameters.
     # The valid options are:
     #
@@ -71,6 +78,11 @@ module Needle
     #   'date_format', and 'message_format' keys, specifying the log level,
     #   date format, and message format for any log whose name matches the key.
     def initialize( opts={} )
+      opts = convert_keys_to_symbols( opts )
+      bad = opts.keys - VALID_OPTIONS
+      raise ArgumentError,
+        "invalid option(s) to LogFactory (#{bad.inspect})" unless bad.empty?
+
       if opts[:device]
         @device = opts[:device]
       else
@@ -87,17 +99,33 @@ module Needle
       @default_level = opts[:default_level]
 
       if @default_level.is_a?( String ) || @default_level.is_a?( Symbol )
-        @default_level = LEVEL_TRANSLATOR[@default_level.to_s]
+        @default_level = LEVEL_TRANSLATOR[@default_level.to_s.upcase]
+        if @default_level.nil?
+          raise ArgumentError,
+            "invalid logging level (#{@default_level.inspect})"
+        end
       end
 
-      @levels = Hash.new "level" => nil, "date-format" => nil,
-        "message-format" => nil
+      @levels = Hash.new :level => nil, :date_format => nil,
+        :message_format => nil
 
       ( opts[:levels] || {} ).each_pair do |key, value|
         key = Regexp.new( "^" + key.gsub( /\./, "\\." ).gsub( /\*/, ".*" ) )
 
         if value.is_a?( String ) || value.is_a?( Symbol )
-          value = { "level" => value.to_s }
+          value = { :level => value.to_s }
+        else
+          value = convert_keys_to_symbols( value )
+        end
+
+        bad = value.keys - VALID_LEVEL_OPTIONS
+        raise ArgumentError, 
+          "invalid log level option(s) #{bad.inspect}" unless bad.empty?
+
+        value[ :level ] = LEVEL_TRANSLATOR[ value[:level].to_s.upcase ]
+        if value[:level].nil?
+          raise ArgumentError,
+            "invalid logging level (#{value[:level].inspect})"
         end
 
         @levels[ key ] = value
@@ -150,6 +178,9 @@ module Needle
     # Retrieves the logger with the given name. If no such log has been
     # created, the log will be created and initialized. Otherwise, the
     # log with the given name is returned.
+    #
+    # If +name+ responds to either +fullname+ or +name+, then the result
+    # of invoking that message on +name+ will be used as the name.
     def get( name )
       name = name.fullname if name.respond_to?( :fullname )
       name = name.name if name.respond_to?( :name )
@@ -164,12 +195,12 @@ module Needle
 
         definition = find_definition( name )
 
-        level = definition[ "level" ] || @default_level
-        date_format = definition[ "date-format" ] || @default_date_format
-        message_format = definition[ "message-format" ] ||
+        level = definition[ :level ] || @default_level
+        date_format = definition[ :date_format ] || @default_date_format
+        message_format = definition[ :message_format ] ||
           @default_message_format
 
-        level = LEVEL_TRANSLATOR[ level ] || level
+        level = LEVEL_TRANSLATOR[ level.to_s.upcase ] || level
 
         logger = Needle::Logger.new( @device )
         logger.level = level if level
@@ -202,6 +233,13 @@ module Needle
       @closed
     end
 
+    # Converts the keys of the given hash to symbols, and returns a new
+    # hash.
+    def convert_keys_to_symbols( hash )
+      Hash[ *hash.collect { |k,v| [ k.to_s.tr('-','_').to_sym, v ] }.flatten ]
+    end
+    private :convert_keys_to_symbols
+
   end
 
 end