carioca 0.1 → 1.0

data/lib/carioca.rb

@@ -1,218 +1,308 @@
+#!/usr/bin/env ruby
+#---
+# Author : Romain GEORGES
+# type : gem component library
+# obj : Carioca Module
+#---
+
 require 'yaml'
 require 'rubygems'
 require 'methodic'
 require 'services'
 require 'daemons'
+require 'carioca_private'
+
 
+
+# module Carioca
+# @author Romain GEORGES <romain@ultragreen.net>
+# @see http://www.ultragreen.net/projects/carioca
+# @version 1.0
+# @note this module is a namespace Carioca
 module Carioca
 
-module Services
-  class Registry
+
+  
+  # module Services
+  # @note this module is a namespace Carioca::Services 
+  module Services
     
     
-    private_class_method :new
-    @@inst = nil
-    def Registry.init(_options = {})
-      options = Methodic::get_options(_options) do |m|
-        m.specify_defaults_value :file => './services.registry', :debug => false
-        m.merge!
-      end
-        
-      @@inst = new(options) if @@inst.nil?
+    # class Registry
+    #  This class provide the Registry manager for Carioca
+    # @note this class is a Singleton Class to instanciate do not use new (initializer), but :
+    #    Carioca::Services::Registry.init options 
+    # @example Complete usage 
+    #    require 'rubygems'
+    #    require 'carioca'  
+    #    registry = Carioca::Services::Registry.init 
+    #    registry = Carioca::Services::Registry.init :file => 'myservices.registry'
+    #    registry = Carioca::Services::Registry.init :file => 'myservices.registry', :debug => true
+    class Registry
+
+      include PrivateMethodsCariocaServicesRegistry
       
+      # for singleton 
+      private_class_method :new
+      private :verify_requires_dependancies
+      private :require_service
+      private :instanciate_service
+      private :kill_service
+
       
-      return @@inst
+      @@inst = nil
       
-    end
-    
-    
-    attr_reader :list
-    attr_reader :loaded_services
-    attr_reader :debug
+      # Singleton constructor for Registry
+      # @param [Hash] _options the options, keys are symbols
+      # @option _options [String] :file The path of your registry YAML definition (see YAML registry format)
+      # @option _options [TrueClass,FalseClass] :debug Boolean activation/deactiviation of the carioca debug mode (log traces) 
+      # @return [Carioca::Services::Registry] Singleton class instance of Registry
+      # @example usage
+      #    registry = Carioca::Services::Registry.init # or  
+      #    registry = Carioca::Services::Registry.init :file => 'myservices.registry' # or
+      #    registry = Carioca::Services::Registry.init :file => 'myservices.registry', :debug => true
+      def Registry.init(_options = {})
+        options = Methodic::get_options(_options) do |m|
+          m.specify_defaults_value :file => './services.registry', :debug => false
+          m.merge!
+        end
+        @@inst = new(options) if @@inst.nil?
+        return @@inst
+      end
+      
+      # @example read
+      #   registry = Carioca::Services::Registry.init
+      #   p registry.registry_filename
+      # @example write
+      #   registry = Carioca::Services::Registry.init
+      #   p registry.registry_filename = '/tmp/test.file'
+      # @attr_reader [Hash] list a hash table of all structured registred services definition 
+      # (come from file and explicitly registered services)
+      attr_accessor :registry_filename
+      
+      # @example 
+      #   registry = Carioca::Services::Registry.init
+      #   p registry.list
+      # @attr_reader [Hash] list a hash table of all structured registred services definition 
+      # (come from file and explicitly registered services)
+      attr_reader :list
 
-    
-    def debug=(_value)
+      # @example 
+      #   registry = Carioca::Services::Registry.init
+      #   p registry.loaded_services # you should see the logger service Hash definition
+      # @attr_reader [Hash] loaded_services a hash table of all structured loaded services 
+      attr_reader :loaded_services
+
+      # @example 
+      #   registry = Carioca::Services::Registry.init
+      #   p registry.debug
+      # @attr_reader [TrueClass,FalseClass] debug a boolean of the current debug status
+      attr_reader :debug
+      
+      # writer accessor for debug (interaction with log service)
+      # @example 
+      #   registry = Carioca::Services::Registry.init
+      #   p registry.debug = true
+      # @param [TrueClass,FalseClass] _value true or false to activate/deactivate debug mode 
+      # @note interaction with preloaded service logger
+      def debug=(_value)
         @log.level =(_value)? Logger::DEBUG : Logger::INFO     
-    end
-
-
-    def stop_service(_options)
-      options = Methodic.get_options(_options)
-      options.specify_class_of :name => String
-      options.specify_presence_of([:name])
-      options.validate!
-      if @loaded_services.include?(options[:name]) then
-        @loaded_engines[options[:name]].garbage if @loaded_services[options[:name]].respond_to? :garbage
-        @loaded_services.delete(options[:name])
-        @log.debug('Carioca') { "Service #{options[:name]} stopped"  } if @log
-        return true
-      else
-        @log.debug('Carioca') { "Service #{options[:name]} not loaded"  } if @log
-        return false
       end
 
-    end
-
-    def register_service(_options)
-      options = Methodic.get_options(_options)
-      options.specify_classes_of({:name => String, :resource => String, :description => String, :type => Symbol, :init_options => Hash, :service => String  }) 
-      options.specify_presences_of([:name,:type,:resource,:service])
-      options.validate!
-      _name = _options.delete(:name)
-      @list[_name] = _options
-      return true
-    end
-    
-    def unregister_service(_options)
-      options = Methodic.get_options(_options = {})
-      options.specify_class_of :name => String
-      options.specify_presence_of :name
-      options.validate!
-      raise RegistryError::new("FONDATION : Can't unregistered the logger service" ) if options[:name] == 'logger'
-      raise RegistryError::new("Can't unregistered a loaded service" ) if @loaded_services.include?(options[:name])
-      @list.delete(options[:name])
-      return true
-    end
-    
-    def discover_builtin
-      Carioca::Services::discover_builtin
-    end
-
-    def save!
-      res = false
-      File.open(@registry_filename, "w") do |f|
-        res = true if f.write(@list.to_yaml)
+
+      # stop a service, if loaded and different to logger
+      # @param [Hash] _options the options, keys are symbols
+      # @option _options [String] :name The name of the service to stop
+      # @return [TruaClass,FalseClass] true if service effectivly stopped, false if not, or :name == 'logger'
+      # @example usage
+      #    registry = Carioca::Services::Registry.init 
+      #    registry.start_service :name => 'configuration'
+      #    registry.stop_service :name => 'configuration'
+      #    #=> return true
+      #    registry.stop_service :name => 'configuration'
+      #    #=> return false
+      #    registry.stop_service :name => 'logger'
+      #    #=> return false
+      # @note log if debug mode
+      def stop_service(_options)
+        options = Methodic.get_options(_options)
+        options.specify_class_of :name => String
+        options.specify_presence_of([:name])
+        options.validate!
+        if @loaded_services.include?(options[:name]) then
+          # prevent logger services killing
+          if options[:name] == 'logger' then
+            @log.debug('Carioca') { "Service logger can't be unloaded" } if @log
+            return false
+          end
+          # calling private killer
+          kill_service options[:name]
+          @log.debug('Carioca') { "Service #{options[:name]} stopped" } if @log
+          return true
+        else
+          @log.debug('Carioca') { "Service #{options[:name]} not loaded" } if @log
+          return false
+        end
+
       end
-      return res
-    end
-    
-    def start_service(_options)
-      options = Methodic.get_options(_options)
-      options.specify_classes_of :name => String, :params => Hash 
-      options.specify_presences_of([:name])
-      options.validate!
-      @log.debug('Carioca') { "getting service #{options[:name]}"} if @log
-      self.restart_service(options) unless @loaded_services.include? options[:name] 
-      return @loaded_services[options[:name]]
-    end
-    
-    alias :get_service :start_service
-
-    def restart_service(_options)
-      options = Methodic.get_options(_options)
-      options.specify_classes_of :name => String, :params => Hash
-      options.specify_presences_of [:name]
-      options.validate!
-      self.stop_service :name => options[:name] if @loaded_services.include? options[:name] 
-      if options[:name] =~ /.*_.*/ then
-        (options[:instance],options[:shortname]) = options[:name].split(/_/) 
-      else
-        options[:shortname] = options[:name]
+
+      # register a new service in registry added to @list
+      # @param [Hash] _options the options hash, key are :symbols
+      # @option _options [String] :name the name of the service (required)
+      # @option _options [String] :resource the resource, must be a gem name, a fullpath filename, a builtin service (required)
+      # @option _options [Symbol] :type the resource type of the service, must be :gem, :builtin or :file (required)
+      # @option _options [String] :service the realname of the service class with namespace (eg. ExternalServices::Dummy ) 
+      # @option _options [String] :description the description of the service (required)
+      # @option _options [Hash] :init_options the params of the service, keys are symbols
+      # @option _options [Array] :requires the list of [String] services name required to load this service
+      # @return [TrueClass,FalseClass] true if service is added
+      # @raise ArgumentError when :type is not in [:gem,:file,:builtin]
+      def register_service(_options)
+        options = Methodic.get_options(_options)
+        options.specify_classes_of({:name => String, :resource => String, :description => String, :type => Symbol, :service => String }) 
+        options.specify_presences_of([:name,:type,:resource,:service])
+        cond = Proc::new{|option| case option 
+                                  when :gem then true 
+                                  when :file then true
+                                  when :builtin then true
+                                  else false end }
+        options.specify_condition_for :type => cond
+        options.validate!
+        _name = _options.delete(:name)
+        @list[_name] = _options
+        return true
       end
-      verify_requires_dependancies(options)
-      require_service(options)
-      return instanciate_service(options)
-    end
-
-    def close
-      @log.debug('Carioca') { "closing Registry ..." }
-      @loaded_services.keys.each do |service|
-        next if service == 'logger' 
-        @log.debug('Carioca') { "Stopping service #{service} ..."} 
-        self.stop_service :name => service
+
+      # unregister a service in registry removed from @list
+      # @param [Hash] _options the options hash, key are :symbols
+      # @option _options [String] :name the name of the service (required)
+      # @raise [RegistryError] if try to unregister logger
+      # @raise [registryerror] if try to unregister a loaded service
+      # @return [TrueClass,FalseClass]
+      def unregister_service(_options = {})
+        options = Methodic.get_options(_options)
+        options.specify_class_of :name => String
+        options.specify_presence_of :name
+        options.validate!
+        raise RegistryError::new("FONDATION : Can't unregistered the logger service" ) if options[:name] == 'logger'
+        raise RegistryError::new("Can't unregistered a loaded service" ) if @loaded_services.include?(options[:name])
+        @list.delete(options[:name])
+        return true
       end
-      @log.debug('Carioca') { "Registry services closed, logger will be closed asynchronously" }
-      self.stop_service :name => 'logger'
-    end
-
-
-    private
-    # private initializer
-    # @param [String] _filename default = '/data/config/service.registry' filename of the service Registry
-    # @return [Registry] Singleton 
-    def initialize(_options)
-      @logger_not_in_reg = false
-      @debug = _options[:debug]
-      @registry_filename = _options[:file]
-      @list  = Hash::new
-      load if File::exist?(@registry_filename)
-      unless @list.include?('logger') then
-        self.register_service({:name => 'logger', 
-                                :service => 'Carioca::Services::InternalLogger',
-                                :resource => 'logger', 
-                                :description => "The standard ruby Logger internal wrapper Service", 
-                                :type => :builtin, 
-                                :init_options => { :target => "/tmp/log.file"}})
-        @logger_not_in_reg = true
-      end 
-        
-      @loaded_services = Hash::new
       
-      @log = self.start_service :name => 'logger' 
-      @log.level =(@debug)? Logger::DEBUG : Logger::INFO     
-      @log.debug('Carioca') { "Registry started, service logger preloaded" }
-      @log.debug('Carioca') { "Logger registered, not in configured registry" } if @logger_not_in_reg
-    end
-
-    def load
-      @list = YAML.load_file(@registry_filename)
-    end
-    
-    private
-    
-    def verify_requires_dependancies(options)
-      _name = options[:shortname]
-      if @list[_name].include?(:requires) then
-        @list[_name][:requires].each do |service|
-          unless @loaded_services.include?(service) then
-            @log.debug('Carioca') { "Registry dependancy found and not loaded : #{service}" }
-            restart_service :name => service 
-          end
+      # overload @list (self.list) by adding/reloading the builtins services definition scanned from Carioca gem
+      #  alterate @list
+      # @example usage
+      #    registry = Carioca::Services::Registry.init :name => '/tmp/empty.file'
+      #    registry.discover_builtins
+      #    registry.save!
+      def discover_builtins
+        @list.merge! Carioca::Services::discover_builtins
+      end
+      
+      # save the registry file in self.registry_filename
+      # @return [TruaClass,FalseClass] true if the file is saved
+      # @example usage
+      #    registry = Carioca::Services::Registry.init :file => './empty.file' 
+      #    registry.discover_builtins
+      #    registry.unregister_service :name => 'configuration'
+      #    registry.save!
+      def save!
+        res = false
+        File.open(@registry_filename, "w") do |f|
+          res = true if f.write(@list.to_yaml)
         end
-      end      
-    end
-
-    def require_service(options)
-      _name = options[:shortname]
-      sym = ":#{@list[_name][:service].split('::').last}"
-      case @list[_name][:type] 
-      when :file then
-        require @list[_name][:resource]
-      when :builtin then
-        _file = Carioca::Services::search_builtins _name
-        if _file then
-          require _file
+        return res
+      end
+      
+      # start or get e previously started service in @list
+      # @return [Object] the loaded service class instance
+      # @param [Hash] _options the params, key are symbols
+      # @option _options [String] :name the name of the service
+      # @option _options [Hash] :params the params of the service
+      # @raise [RegistryError] Config Failed, for unconsistant service definition in @list
+      # @example usage 
+      #    registry = Carioca::Services::Registry.init 
+      #    config = registry.start_service :name => 'configuration'
+      #    proxy = subject.start_service :name => 'debug' , :params => {:service => 'configuration'}
+      def start_service(_options)
+        options = Methodic.get_options(_options)
+        options.specify_classes_of :name => String
+        options.specify_presences_of([:name])
+        options.validate!
+        @log.debug('Carioca') { "getting service #{options[:name]}"} if @log
+        self.restart_service(options) unless @loaded_services.include? options[:name] 
+        return @loaded_services[options[:name]]
+      end
+      alias :get_service :start_service
+
+      # start or restart (stop=>start) previously started service in @list
+      # @return [Object] the loaded service class instance
+      # @param [Hash] _options the params, key are symbols
+      # @option _options [String] :name the name of the service
+      # @option _options [Hash] :params the params of the service
+      # @raise [RegistryError] Config Failed, for unconsistant service definition in @list
+      # @example usage 
+      #    registry = Carioca::Services::Registry.init 
+      #    config = registry.restart_service :name => 'configuration'
+      #    config = registry.restart_service :name => 'configuration' # stop and restart the previous services
+      #    proxy = subject.restart_service :name => 'debug' , :params => {:service => 'configuration'}
+      # @note Registry and services are Singleton
+      def restart_service(_options)
+        options = Methodic.get_options(_options)
+        options.specify_classes_of :name => String
+        options.specify_presences_of [:name]
+        options.validate!
+        
+        if @loaded_services.include? options[:name] then
+          @log.debug('Carioca') { "Restarting service #{options[:name]}"} if @log
+          kill_service :name => options[:name]     
+        end    
+        if options[:name] =~ /.*_.*/ then
+          (options[:shortname],options[:instance]) = options[:name].split(/_/) 
         else
-          raise RegistryError::new("Config failed")
+          options[:shortname] = options[:name]
         end
-      when :gem then
-        eval("require '#{@list[_name][:resource]}'") 
-      else 
-        raise RegistryError::new("Config failed")
+        verify_requires_dependancies(options)
+        require_service(options)
+        return instanciate_service(options)
       end
-    end
-
-    def instanciate_service(options)
-      _name = options[:shortname]
-      @list[_name][:init_options] = options[:params] unless options[:params].nil?
-      if @list[_name][:init_options].nil? then 
-        eval("@loaded_services[options[:name]] = #{@list[_name][:service]}::new")
-      else
-        eval("@loaded_services[options[:name]] = #{@list[_name][:service]}::new(@list[_name][:init_options])")
+      
+      # close the registry (finalizer)
+      #  * stop all the services 
+      #  * kill logger
+      #  * call private kill_service for each 
+      # @note the garbage method hook is call if defined, for each service
+      # @return [TrueClass,FalseClass] true if registry closed successfully
+      def close
+        @log.debug('Carioca') { "closing Registry ..." }
+        @loaded_services.keys.each do |service|
+          next if service == 'logger' 
+          @log.debug('Carioca') { "Stopping service #{service} ..."} 
+          self.stop_service :name => service
+        end
+        @log.debug('Carioca') { "Registry services closed, logger will be closed asynchronously" }
+        kill_service 'logger'
+        return true
       end
-      @log.debug('Carioca') { "Service #{options[:name]} started" } if @log
-      return @loaded_services[options[:name]]
-    end
-
-    
-  end
-end
-
-
-
-end
 
+      # load the registry file from self.registry_filename
+      # @return [Hash] @list the list Structure of the loaded registry 
+      # @example usage
+      #    registry = Carioca::Services::Registry.init
+      #    registry.registry_filename = "./an_other.file"
+      #    registry.load #or
+      #    registry.reload
+      def load
+        @list = YAML.load_file(@registry_filename)
+      end
+      alias :reload :load
+      
+    end # end of Carioca::Services::Registry
+  end # end of Carioca:Services
+end # end of Carioca
 
+# Exception overload class for Carioca 
 class RegistryError < Exception; end