patriarch 0.2.3 → 0.2.4

data/lib/patriarch/dao_services/bipartite_relationship_builder_service.rb

@@ -1,6 +1,14 @@
 require "redis/objects/sorted_sets"
 
+# Patriarch::Transaction instances are composed of transaction steps that each represent
+# a behaviour being triggered. RelationshipBuilderServices allow Services managing transaction
+# flow to build transaction step correctly. This deals with transaction step needed to represent
+# bipartite behaviours
 class Patriarch::DAOServices::BipartiteRelationshipBuilderService < Patriarch::Service
+
+  # @param [Patriarch::Transaction] transaction_item
+  # Fills current transaction step of the Patriarch::Transaction argument passed with data needed
+  # later to execute transaction. This deals with "DO" behaviour steps
   def create(transaction_item)
     t = Time.now.to_f
     dao_tab = Patriarch::DAOServices::RetrieverService.instance.call(transaction_item)
@@ -16,6 +24,9 @@ class Patriarch::DAOServices::BipartiteRelationshipBuilderService < Patriarch::S
     transaction_item.add_to_queue ll
   end
 
+  # @param [Patriarch::Transaction] transaction_item
+  # Fills current transaction step of the Patriarch::Transaction argument passed with data needed
+  # later to execute transaction. This deals with "UNDO" behaviour steps
   def destroy(transaction_item)
     dao_tab = Patriarch::DAOServices::RetrieverService.instance.call(transaction_item)
     
@@ -33,7 +44,10 @@ class Patriarch::DAOServices::BipartiteRelationshipBuilderService < Patriarch::S
   end
 
   protected
-
+  # @param [Redis::Objects] dao
+  # @param [Array] ids
+  # @param [Time] time
+  # Returns lambda objects that store a redis operation
   def build_lambda_for_create(dao,id,time)
     if dao.is_a? Redis::SortedSet
       return lambda { dao.add id, time }

data/lib/patriarch/dao_services/redis_mapper_service.rb

@@ -1,22 +1,30 @@
+# This service is in charge of the redis mapping.
+# When wanting to retrieve DAOs needed for a transaction, we may want to retrieve Redis DAO
+# For each situation e.g. (in a given transaction, with a given protagonist that has an unique role), the
+# service will return the configuration needed to achieve DAO build. Hence it enforces conventions
 class Patriarch::DAOServices::RedisMapperService < Patriarch::Service
-  def call(transac,protagonist_type)
-    
+
+  # @param [Patriach::Transaction]transaction the transaction being processed
+  # @param [Symbol] protagonist_type the type of the protagonist whose DAO is needed
+  # @return [Hash] hash with configuration needed to achieve DAO build
+  def call(transaction,protagonist_type)
+
     # Getting symbols here ...
-    relation_type     = transac.relation_type
-    actor_type        = transac.actor_type
-    target_type       = transac.target_type
-    medium_type       = transac.medium_type
-  
+    relation_type     = transaction.relation_type
+    actor_type        = transaction.actor_type
+    target_type       = transaction.target_type
+    medium_type       = transaction.medium_type
+
     relation_type_str = sanitize_relation_type(relation_type.to_s)
 
-    if transac.tripartite?
+    if transaction.tripartite?
       if protagonist_type == :actor
         redis_tripartite_config_for_actor(target_type,medium_type,relation_type_str)
       elsif protagonist_type == :target
         redis_tripartite_config_for_target(actor_type,medium_type,relation_type_str)
       elsif protagonist_type == :medium
        redis_tripartite_config_for_medium(actor_type,target_type,relation_type_str)
-      end 
+      end
     else
       if protagonist_type == :actor
         redis_bipartite_config_for_actor(target_type,relation_type_str)
@@ -26,53 +34,74 @@ class Patriarch::DAOServices::RedisMapperService < Patriarch::Service
     end
   end
 
+  # @param [String] target_model_name
+  # @param [String] relation_type_str
+  # @return [Hash] a hash containing configuration to build actor DAO used in bipartite transactions
   def redis_bipartite_config_for_actor(target_model_name,relation_type_str)
-    # example : items_i_like ...    
-    { 
-      :type => "sorted_set", 
+    # example : items_i_like ...
+    {
+      :type => "sorted_set",
       :key => "patriarch_#{target_model_name.to_s.tableize}_i_#{relation_type_str}"
     }
   end
 
+  # @param [String] target_model_name
+  # @param [String] relation_type_str
+  # @return [Hash] a hash containing configuration to build target DAO used in bipartite transactions
   def redis_bipartite_config_for_target(actor_model_name,relation_type_str)
     # example : items_liking_me ...
-    { 
-      :type => "sorted_set", 
+    {
+      :type => "sorted_set",
       :key => "patriarch_#{actor_model_name.to_s.tableize}_#{progressive_present(relation_type_str)}_me"
     }
-  end  
+  end
 
+  # @param [String] target_model_name
+  # @param [String] relation_type_str
+  # @return [Hash] a hash containing configuration to build actor DAO used in tripartite transactions
   def redis_tripartite_config_for_actor(target_model_name,medium_model_name,relation_type_str)
-    { 
-      :type => "sorted_set", 
+    {
+      :type => "sorted_set",
       :key => "patriarch_#{target_model_name.to_s.tableize}_i_#{relation_type_str}_via_#{medium_model_name.to_s.tableize}",
       :options => { :marshal => true }
     }
   end
-  
+
+  # @param [String] target_model_name
+  # @param [String] relation_type_str
+  # @return [Hash] a hash containing configuration to build medium DAO used in tripartite transactions
   def redis_tripartite_config_for_medium(actor_model_name,target_model_name,relation_type_str)
-    { 
-      :type => "sorted_set", 
+    {
+      :type => "sorted_set",
       :key => "patriarch_#{actor_model_name.to_s.tableize}_#{progressive_present(relation_type_str)}_#{target_model_name.to_s.tableize}_via_me",
-      :options => { :marshal => true }      
-    }       
+      :options => { :marshal => true }
+    }
   end
 
+  # @param [String] target_model_name
+  # @param [String] relation_type_str
+  # @return [Hash] a hash containing configuration to build target DAO used in tripartite transactions
   def redis_tripartite_config_for_target(actor_model_name,medium_model_name,relation_type_str)
     # example : items_praising_me_via_comments
-    { 
-      :type => "sorted_set", 
+    {
+      :type => "sorted_set",
       :key => "patriarch_#{actor_model_name.to_s.tableize}_#{progressive_present(relation_type_str)}_me_via_#{medium_model_name.to_s.tableize}",
-      :options => { :marshal => true }      
-    }       
+      :options => { :marshal => true }
+    }
   end
 
+  # Little helper to put behaviour verbs to progressive form, relies on gem 'Verbs'
+  # @param [String] behaviour_verb the verb to conjugate
+  # @return [String] progressive form of behaviour_verb
   def progressive_present(behaviour_verb)
     # like becomes => liking
     (Verbs::Conjugator.conjugate behaviour_verb.to_sym, :aspect => :progressive).split(/ /).last
   end
 
+  # Helper to sanitize relation type string that is equivalent to behaviour verb with a prefix to its base root.
+  # DAO and DB storage are agnostic about what kind of operation is being performed on them, hence we dont
+  # need to know if it will be an undo or a 'do'.
   def sanitize_relation_type(relation_type)
     relation_type.sub(/^undo_/,'')
   end
-end
+end

data/lib/patriarch/dao_services/retriever_service.rb

@@ -3,37 +3,45 @@ require 'redis/objects/sorted_sets'
 class InvalidRedisTypeException < Exception
 end
 
+# Services managing transactions must not know how the database layer is structured.
+# We thus provide DAO through this RetrieverService and let them know about the interface of the DAOs
 class Patriarch::DAOServices::RetrieverService < Patriarch::Service
-  # go hash
-  def call(transaction_item)     
+
+  # @return [Hash] hash containing DAOs for RelationshipBuilderServices to toy with
+  # @param  [Patriarch::Transaction] transaction_item
+  # Only public method of this service, does the work of retrieving DAOs for a given transaction step
+  def call(transaction_item)
     result = {}
     result[:actor]  = instantiate_DAO_for_actor(transaction_item)
     result[:target] = instantiate_DAO_for_target(transaction_item)
     if transaction_item.tripartite?
-      result[:medium] = instantiate_DAO_for_medium(transaction_item)    
+      result[:medium] = instantiate_DAO_for_medium(transaction_item)
     end
-    result  
+    result
   end
 
   protected
-
+  #:nodoc:
   def get_DAO_info_for_actor(transaction_item)
     Patriarch::DAOServices::RedisMapperService.instance.call(transaction_item,:actor)
   end
 
-  def get_DAO_info_for_target(transaction_item)
+  #:nodoc
+    def get_DAO_info_for_target(transaction_item)
     Patriarch::DAOServices::RedisMapperService.instance.call(transaction_item,:target)
   end
-  
+
+  #:nodoc
   def get_DAO_info_for_medium(transaction_item)
     Patriarch::DAOServices::RedisMapperService.instance.call(transaction_item,:medium)
   end
 
+  #:nodoc:
   def instantiate_DAO_for_actor(transaction_item)
-    dao_info = get_DAO_info_for_actor(transaction_item) 
+    dao_info = get_DAO_info_for_actor(transaction_item)
     actor_id = transaction_item.actor_id
     actor_type = transaction_item.actor_type
-    
+
     if Redis::Objects.constants.map(&:to_s).include?("#{dao_info[:type].pluralize.camelize}")
       redis_dao_class = "Redis::#{dao_info[:type].camelize}".constantize
     else
@@ -42,12 +50,14 @@ class Patriarch::DAOServices::RetrieverService < Patriarch::Service
 
     redis_dao_class.new("#{actor_type}:#{actor_id}:#{dao_info[:key]}",dao_info[:options])
   end
-  
+
+
+  #:nodoc:
   def instantiate_DAO_for_medium(transaction_item)
-    dao_info = get_DAO_info_for_medium(transaction_item) 
+    dao_info = get_DAO_info_for_medium(transaction_item)
     medium_id = transaction_item.medium_id
     medium_type = transaction_item.medium_type
-    
+
     if Redis::Objects.constants.map(&:to_s).include?("#{dao_info[:type].pluralize.camelize}")
       redis_dao_class = "Redis::#{dao_info[:type].camelize}".constantize
     else
@@ -55,19 +65,21 @@ class Patriarch::DAOServices::RetrieverService < Patriarch::Service
     end
 
     redis_dao_class.new("#{medium_type}:#{medium_id}:#{dao_info[:key]}",dao_info[:options])
-  end  
+  end
+
 
+  #:nodoc:
   def instantiate_DAO_for_target(transaction_item)
     dao_info = get_DAO_info_for_target(transaction_item)
     target_id = transaction_item.target_id
-    target_type = transaction_item.target_type  
+    target_type = transaction_item.target_type
 
     if Redis::Objects.constants.map(&:to_s).include?("#{dao_info[:type].pluralize.camelize}")
       redis_dao_class = "Redis::#{dao_info[:type].camelize}".constantize
     else
       raise InvalidRedisTypeException, "Redis constants available were #{Redis::Objects.constants} and supplied type was #{dao_info[:type]}"
     end
-    redis_dao_class.new("#{target_type}:#{target_id}:#{dao_info[:key]}",dao_info[:options])    
+    redis_dao_class.new("#{target_type}:#{target_id}:#{dao_info[:key]}",dao_info[:options])
   end
 end
 

data/lib/patriarch/dao_services/tripartite_relationship_builder_service.rb

@@ -1,33 +1,45 @@
 require "redis/objects/sorted_sets"
 
+
+# Patriarch::Transaction instances are composed of transaction steps that each represent
+# a behaviour being triggered. RelationshipBuilderServices allow Services managing transaction
+# flow to build transaction step correctly. This deals with transaction step needed to represent
+# tripartite behaviours
 class Patriarch::DAOServices::TripartiteRelationshipBuilderService < Patriarch::Service
+
+  # @param [Patriarch::Transaction] transaction_item
+  # Fills current transaction step of the Patriarch::Transaction argument passed with data needed
+  # later to execute transaction. This deals with "DO" behaviour steps
   def create(transaction_item)
     t = Time.now.to_f
     dao_tab = Patriarch::DAOServices::RetrieverService.instance.call(transaction_item)
-    
+
     actor_dao = dao_tab[:actor]
     target_dao = dao_tab[:target]
-    medium_dao = dao_tab[:medium]    
+    medium_dao = dao_tab[:medium]
 
     protagonist_ids = [transaction_item.actor_id,transaction_item.target_id,transaction_item.medium_id]
 
     l    = build_lambda_for_create(actor_dao,protagonist_ids,t)
     ll   = build_lambda_for_create(target_dao,protagonist_ids,t)
     lll  = build_lambda_for_create(medium_dao,protagonist_ids,t)
- 
+
     # care about that, should be encapsulated into a beautiful add_to_queue method
     transaction_item.add_to_queue l
     transaction_item.add_to_queue ll
-    transaction_item.add_to_queue lll    
+    transaction_item.add_to_queue lll
   end
 
+  # @param [Patriarch::Transaction] transaction_item
+  # Fills current transaction step of the Patriarch::Transaction argument passed with data needed
+  # later to execute transaction. This deals with "UNDO" behaviour steps
   def destroy(transaction_item)
     dao_tab = Patriarch::DAOServices::RetrieverService.instance.call(transaction_item)
-    
+
     actor_dao = dao_tab[:actor]
     target_dao = dao_tab[:target]
-    medium_dao = dao_tab[:medium]    
-    
+    medium_dao = dao_tab[:medium]
+
     protagonist_ids = [transaction_item.actor_id,transaction_item.target_id,transaction_item.medium_id]
 
     l   = lambda { actor_dao.delete protagonist_ids }
@@ -36,11 +48,14 @@ class Patriarch::DAOServices::TripartiteRelationshipBuilderService < Patriarch::
 
     transaction_item.add_to_queue l
     transaction_item.add_to_queue ll
-    transaction_item.add_to_queue lll    
+    transaction_item.add_to_queue lll
   end
 
   protected
-
+  # @param [Redis::Objects] dao
+  # @param [Array] ids
+  # @param [Time] time
+  # Returns lambda objects that store a redis operation
   def build_lambda_for_create(dao,ids,time)
     if dao.is_a? Redis::SortedSet
       return lambda { dao.add ids, time }

data/lib/patriarch/manager_service.rb

@@ -1,6 +1,7 @@
 require 'singleton'
 
 module Patriarch
+  # Mother class of all Manager Services
   class ManagerService
     include Singleton
   end

data/lib/patriarch/service.rb

@@ -1,5 +1,8 @@
 require 'singleton'
 
-class Patriarch::Service
-  include Singleton 
+module Patriarch
+  # Mother class of all services
+  class Service
+    include Singleton
+  end
 end

data/lib/patriarch/tool_services/redis_cleaner_service.rb

@@ -1,6 +1,13 @@
+# Adding behaviours to classes through Patriarch induces writes in Redis Database
+# What happens when we want to destroy an item is that it fires ActiveRecord::Callbacks to deal
+# with this kind of stuff. We build a transaction item whose execute would clean redis stuff
+# but do nothing until commit happens in case SQL aborts.
+# This service takes care of building clean items
 class Patriarch::ToolServices::RedisCleanerService < Patriarch::Service
-  
-  # Shall be tested before implementation ...  
+
+  # @param [Object] calling_entity the entity calling the clean upon itself
+  # @param [Object] options various options we may want to pass, used here to transmit a transaction item if a clean transaction wraps all the clean
+  # @return [Patriarch::Transaction] returns a transaction item that is either built from scratch or was passed through options and has been completed
   def clean_all(calling_entity,options={})
     transac = options[:transac] || Patriarch::TransactionServices::TransactionManagerService.instance.new_transaction("clean_all".to_sym)
     options = { :transac => transac }
@@ -12,11 +19,17 @@ class Patriarch::ToolServices::RedisCleanerService < Patriarch::Service
     transac
   end
 
+  # @return [Patriarch::Transaction] returns a transaction item that is either built from scratch or was passed through options and has been completed
+  # @param [Object] calling_entity the entity calling the clean upon itself
+  # @param [Object] behaviour the behaviour the entity wants to clean
+  # @param [Object] options various options we may want to pass, used here to transmit a transaction item if a clean transaction wraps all the clean
+  # behaviours so it runs once and not multiple transactions.
   def clean_behaviour(calling_entity,behaviour,options={})
     my_behaviours = calling_entity.class.patriarch_behaviours
-    
-    if my_behaviours.include? behaviour.to_s.underscore.to_sym
-      if my_behaviours[behaviour.to_s.underscore.to_sym][:medium_between] || my_behaviours[behaviour.to_s.underscore.to_sym][:via]
+    behaviour_symbol = behaviour.to_s.underscore.to_sym
+
+    if my_behaviours.include? behaviour_symbol
+      if my_behaviours[behaviour_symbol][:medium_between] || my_behaviours[behaviour_symbol][:via]
         clean_tripartite_behaviour(calling_entity,behaviour,options)
       else
         clean_bipartite_behaviour(calling_entity,behaviour,options)
@@ -24,24 +37,24 @@ class Patriarch::ToolServices::RedisCleanerService < Patriarch::Service
     end
   end
 
-
-#Copiepat
+  #:nodoc:
   def clean_tripartite_behaviour(calling_entity,behaviour,options={})
     my_behaviours = calling_entity.class.patriarch_behaviours
-    
-    # Compute names based on conventions    
-    progressive_present_behaviour = 
-      (Verbs::Conjugator.conjugate behaviour.to_s.underscore.to_sym, :aspect => :progressive).split(/ /).last
+    behaviour_symbol = behaviour.to_s.underscore.to_sym
+
+    # Compute names based on conventions
+    progressive_present_behaviour =
+      (Verbs::Conjugator.conjugate behaviour_symbol, :aspect => :progressive).split(/ /).last
 
     transac = options[:transac] || Patriarch::TransactionServices::TransactionManagerService.instance.new_transaction("clean_#{behaviour.to_s}".to_sym)
     options = { :transac => transac, :stop_execution => true}
 
-    if my_behaviours.include? behaviour.to_s.underscore.to_sym
+    if my_behaviours.include? behaviour_symbol
 
       # Dealing with active behaviour
-      if my_behaviours[behaviour.to_s.underscore.to_sym][:on]
-        acted_on_models = my_behaviours[behaviour.to_s.underscore.to_sym][:on]
-        via_models      = my_behaviours[behaviour.to_s.underscore.to_sym][:via]
+      if my_behaviours[behaviour_symbol][:on]
+        acted_on_models = my_behaviours[behaviour_symbol][:on]
+        via_models      = my_behaviours[behaviour_symbol][:via]
         acted_on_models.each do |acted_on_model|
           via_models.each do |via_model|
             calling_entity.send("#{acted_on_model.to_s.tableize}_i_#{behaviour.to_s}_via_#{via_model.to_s.tableize}", :with_medium => true).each do |tripartite_hash|
@@ -52,13 +65,13 @@ class Patriarch::ToolServices::RedisCleanerService < Patriarch::Service
           end
         end
       end
-      
+
       # Dealing with passive behaviour
-      if my_behaviours[behaviour.to_s.underscore.to_sym][:by]
-        targetted_by_models = my_behaviours[behaviour.to_s.underscore.to_sym][:by]
-        via_models      = my_behaviours[behaviour.to_s.underscore.to_sym][:via]        
+      if my_behaviours[behaviour_symbol][:by]
+        targetted_by_models = my_behaviours[behaviour_symbol][:by]
+        via_models      = my_behaviours[behaviour_symbol][:via]
         targetted_by_models.each do |targetted_by_model|
-          via_models.each do |via_model|          
+          via_models.each do |via_model|
             calling_entity.send("#{targetted_by_model.to_s.tableize}_#{progressive_present_behaviour}_me_via_#{via_model.to_s.tableize}", :with_medium => true).each do |tripartite_hash|
               #
               actor_that_behaved_on_me = Array(targetted_by_model.to_s.classify.constantize.find(tripartite_hash[:actor])).first
@@ -71,46 +84,46 @@ class Patriarch::ToolServices::RedisCleanerService < Patriarch::Service
       end
 
       # Dealing with medium behaviour
-      if my_behaviours[behaviour.to_s.underscore.to_sym][:medium_between]
+      if my_behaviours[behaviour_symbol][:medium_between]
         #do nothing, we do not take care of data relative to medium ...
-      end      
+      end
     end # if my_behaviours.include?
 
-    transac  
+    transac
   end #clean_tripartite_behaviour
 
-
-
+  #:nodoc:
   def clean_bipartite_behaviour(calling_entity,behaviour,options={})
     my_behaviours = calling_entity.class.patriarch_behaviours
-    
-    # Compute names based on conventions    
-    progressive_present_behaviour = 
-      (Verbs::Conjugator.conjugate behaviour.to_s.underscore.to_sym, :aspect => :progressive).split(/ /).last
+    behaviour_symbol = behaviour.to_s.underscore.to_sym
+
+    # Compute names based on conventions
+    progressive_present_behaviour =
+      (Verbs::Conjugator.conjugate behaviour_symbol, :aspect => :progressive).split(/ /).last
 
     transac = options[:transac] || Patriarch::TransactionServices::TransactionManagerService.instance.new_transaction("clean_#{behaviour.to_s}".to_sym)
     options = { :transac => transac, :stop_execution => true}
 
-    if my_behaviours.include? behaviour.to_s.underscore.to_sym
+    if my_behaviours.include? behaviour_symbol
       # Dealing with passive behaviour
-      if my_behaviours[behaviour.to_s.underscore.to_sym][:by]
-        targetted_by_models = my_behaviours[behaviour.to_s.underscore.to_sym][:by]
-        targetted_by_models.each do |targetted_by_model|
-          calling_entity.send("#{targetted_by_model.to_s.tableize}_#{progressive_present_behaviour}_me").each do |target_that_behaved_on_me|
+      if my_behaviours[behaviour_symbol][:by]
+        targeted_by_models = my_behaviours[behaviour_symbol][:by]
+        targeted_by_models.each do |targeted_by_model|
+          calling_entity.send("#{targeted_by_model.to_s.tableize}_#{progressive_present_behaviour}_me").each do |target_that_behaved_on_me|
             target_that_behaved_on_me.send(Patriarch.undo(behaviour.to_s).underscore,calling_entity,options)
           end
         end
       end
       # Dealing with active behaviour
-      if my_behaviours[behaviour.to_s.underscore.to_sym][:on]
-        acted_on_models = my_behaviours[behaviour.to_s.underscore.to_sym][:on]
+      if my_behaviours[behaviour_symbol][:on]
+        acted_on_models = my_behaviours[behaviour_symbol][:on]
         acted_on_models.each do |acted_on_model|
           calling_entity.send("#{acted_on_model.to_s.tableize}_i_#{behaviour.to_s}").each do |target_i_behaved_on|
             calling_entity.send(Patriarch.undo(behaviour.to_s).underscore,target_i_behaved_on,options)
           end
         end
       end
-      
+
 
     end # if my_behaviours.include?