your_platform 0.0.1 → 0.0.2

data/app/models/user_group_membership_mixins/validity_range.rb

@@ -0,0 +1,206 @@
+#
+# In this project, user group memberships do not neccessarily last forever.
+# They can begin at some time and end at some time. This is expressed by the
+# ValidityRange of a membership.
+#
+# Examples:
+#
+#     membership.valid_from  # =>  time
+#     membership.valid_to    # =>  time
+#     membership.invalidate
+# 
+# Scopes:
+#
+#     UserGroupMembership.with_invalid
+#     UserGroupMembership.only_valid
+#     UserGroupMembership.only_invalid
+#     UserGroupMembership.at_time(time)
+#
+# By default, the `only_valid` scope is applied, i.e. only memberships are 
+# found that are valid at present time. To override this scope, use either
+# `with_invalid` or `unscoped`.
+#
+module UserGroupMembershipMixins::ValidityRange
+  
+  extend ActiveSupport::Concern
+
+  included do 
+    attr_accessible :valid_from, :valid_to, :valid_from_localized_date, :valid_to_localized_date
+    before_validation :set_valid_from_to_now
+    
+    default_scope { only_valid }
+  end
+  
+  
+  # Attributes in the database
+  # ====================================================================================================
+  
+  def valid_from_localized_date
+    self.valid_from ? I18n.localize(self.valid_from.try(:to_date)) : ""
+  end
+  def valid_from_localized_date=(new_date)
+    self.valid_from = new_date.to_datetime
+    valid_from_will_change!
+  end
+
+  def set_valid_from_to_now(force = false)
+    self.valid_from ||= Time.zone.now if self.new_record? or force
+    return self
+  end
+  
+  def valid_to_localized_date
+    self.valid_to ? I18n.localize(self.valid_to.try(:to_date)) : ""
+  end
+  def valid_to_localized_date=(new_date)
+    if new_date == "-"
+      self.valid_to = nil
+    else
+      self.valid_to = new_date.to_datetime
+    end
+    valid_to_will_change!
+  end
+  
+  
+  # Invalidation
+  # ====================================================================================================
+  
+  # This method ends the membership, i.e. sets the end of the validity range
+  # to the given time.
+  # 
+  # The following examples are equivalent (despite the return value):
+  # 
+  #     membership.make_invalid
+  #     membership.make_invalid at: Time.zone.now
+  #     membership.make_invalid Time.zone.now
+  #     membership.invalidate                                    #  => membership
+  #     membership.update_attribute :valid_to, Time.zone.now     #  => true
+  #     
+  def make_invalid(time = Time.zone.now)
+    time = time[:at] if time.kind_of?(Hash) && time[:at]
+    self.update_attribute(:valid_to, time)
+    return self
+  end
+  
+  # This is just an alias for `make_invalid`.
+  #
+  def invalidate(time = Time.zone.now)
+    self.make_invalid(time)
+  end
+  
+  # This method determines whether the membership can be invalidated.
+  # Direct memberships can be invalidated, whereas indirect memberships cannot.
+  # The validity of indirect memberships is derived from the validity of the direct ones.
+  #
+  def can_be_invalidated?
+    self.direct?
+  end
+
+
+  # Validity Check
+  # ====================================================================================================
+  
+  # This method checks whether the membership is valid at the given time.
+  #
+  # This is not to be confused with ActiveRecord's `valid` method, which checks whether the
+  # record matches the requirements to store it in the database.
+  #
+  # The following examples are equivalent:
+  #
+  #     membership.currently_valid?
+  #     membership.valid_at? Time.zone.now
+  # 
+  def valid_at?(time)
+    (self.valid_from == nil || self.valid_from <= time) && (self.valid_to == nil || self.valid_to >= time)
+  end
+
+  # This method checks whether the present time lies within the validity range
+  # of the membership.
+  #
+  def currently_valid?
+    valid_at?(Time.zone.now)
+  end
+
+
+  # Temporal scopes
+  # ====================================================================================================
+  
+  module ClassMethods
+  
+    # This scope returns limits the query to memberships whose validity ranges match the
+    # given time.
+    #
+    # Example:
+    #
+    #     UserGroupMembership.find_all_by_user( u ).at_time( 1.hour.ago ).count
+    #
+    def at_time( time )
+      with_invalid
+        .where("valid_from IS NULL OR valid_from <= ?", time)
+        .where("valid_to IS NULL OR valid_to >= ?", time)
+    end
+    
+    # This scope limits the query to memberships that are valid at the present time.
+    # This is the default bahaviour. 
+    #
+    def only_valid
+      where("valid_from IS NULL OR valid_from <= ?", Time.zone.now)
+      .where("valid_to IS NULL OR valid_to >= ?", Time.zone.now)
+    end
+    
+    # This scope widens the query such that also memberships that are not valid at the
+    # present time are returned.
+    # 
+    def with_invalid
+
+      # TODO: Replace the brute-force `unscoped` by a more specific term like
+      # `except(:valid_from).except(:valid_to)`. 
+      # But so far, this has caused several tests to fail, which would have to be 
+      # fixed.
+      #
+      unscoped
+
+    end
+    
+    # This scope limits the query to memberships that are invalid at the present time.
+    # 
+    def only_invalid
+      with_invalid.where("valid_to < ?", Time.zone.now)
+    end
+    
+    # This scope limits the query to memberships that are valid at the present time.
+    # This is the default bahaviour. 
+    #
+    def now
+      only_valid
+    end
+
+    # This scope limits the query to memberships that are invalid at the present time.
+    # 
+    def in_the_past
+      only_invalid
+    end
+
+    # This scope widens the query such that also memberships that are not valid at the
+    # present time are returned.
+    # 
+    def now_and_in_the_past
+      with_invalid
+    end
+    
+    def this_year
+      with_invalid.where("valid_from >= ?", "#{Time.zone.now.year}-01-01 00:00:00")
+    end
+    
+    def started_after(time)
+      where('NOT valid_from IS NULL').where("valid_from >= ?", time)
+    end
+  
+  end
+  
+end
+
+class Array
+  def started_after(time)
+    self.select { |membership| membership.valid_from && membership.valid_from >= time }
+  end
+end

data/app/models/user_group_membership_mixins/validity_range_for_indirect_memberships.rb

@@ -0,0 +1,160 @@
+#
+# In this project, user group memberships do not neccessarily last forever.
+# They can begin at some time and end at some time. This is expressed by the
+# ValidityRange of a membership.
+#
+# Examples:
+#
+#     membership.valid_from  # =>  time
+#     membership.valid_to    # =>  time
+#     membership.invalidate
+# 
+# Scopes:
+#
+#     UserGroupMembership.with_invalid
+#     UserGroupMembership.only_valid
+#     UserGroupMembership.only_invalid
+#     UserGroupMembership.at_time(time)
+#
+# By default, the `only_valid` scope is applied, i.e. only memberships are 
+# found that are valid at present time. To override this scope, use either
+# `with_invalid` or `unscoped`.
+#
+module UserGroupMembershipMixins::ValidityRangeForIndirectMemberships
+  
+  extend ActiveSupport::Concern
+  
+  included do
+    after_save :recalculate_indirect_validity_ranges_if_needed
+  end
+
+
+  # Validity Range Attributes
+  # ====================================================================================================
+  
+  # The validity range attributes are inherited for indirect memberships.
+  #
+  #       *-----------------(c)--------------------*
+  #                          |
+  #                |--------------------|
+  #                |                    |
+  #       *-------(a)--------*          | 
+  #                          *---------(b)---------*
+  #
+  #       _________________________________________________________
+  #       t1                 t2                    t3      time -->
+  #
+  # If membership A is valid from t1 to t2 and membership B is valid from t2 to t3
+  # and membership C is the indirect membership that results from the memberships
+  # A and B, then C is valid from t1 to t3.
+  #
+  # This means that the valid_from attribute is derived from the valid_from attribute
+  # of the earliest direct membership. The valid_to attribute is derived from the
+  # latest direct membership.
+  #
+  def earliest_direct_membership
+    @earliest_direct_membership ||= direct_memberships(with_invalid: true).reorder('valid_from').first
+  end
+  
+  def latest_direct_membership
+    @latest_direct_membership ||= direct_memberships.only_valid.last
+    @latest_direct_membership ||= direct_memberships(with_invalid: true).reorder('valid_to').last
+  end
+  
+  def valid_from
+    self.direct? ? super : cached { earliest_direct_membership.try(:valid_from) }
+  end
+  def valid_from=( valid_from )
+    if self.direct? 
+      super(valid_from) 
+      @need_to_recalculate_indirect_memberships = true
+    else
+      earliest_direct_membership.try(:valid_from=, valid_from)
+    end
+  end
+  
+  def valid_to
+    self.direct? ? super : latest_direct_membership.try(:valid_to)
+  end
+  def valid_to=( valid_to )
+    if self.direct? 
+      super(valid_to) 
+      @need_to_recalculate_indirect_memberships = true
+    else
+      latest_direct_membership.try(:valid_to=, valid_to)
+    end
+  end
+
+  # Save the current membership and auto-save also the direct memberships
+  # associated with the current (maybe indirect) membership.
+  #
+  def save(*args)
+    super(*args)
+    unless self.direct?
+      earliest_direct_membership.try(:save)
+      latest_direct_membership.try(:save)
+    end
+  end
+
+  # This method recalculates the validity range for an indirect membership.
+  # This becomes necessary whenever the validity range of a direct membership is changed, so that
+  # the validity range of the indirect memberships can be used in database queries,
+  # for example, when using scopes.
+  #
+  # **Attention**: At this point, this mechanism does not cover the validity range of
+  # indirect memberships where there should be a gap in the membership:
+  # 
+  #     *----------*     *----------* (indirect membership with gap in validity range)
+  #          |--------|--------|
+  #     *----------*           |      (direct membership 1)
+  #                      *----------* (direct membership 2)
+  #
+  # TODO: This has to be fiexed, probably when switching to neo4j.
+  #
+  def recalculate_validity_range_from_direct_memberships
+    unless direct?
+      write_attribute :valid_from, earliest_direct_membership.try(:valid_from)
+      write_attribute :valid_to, latest_direct_membership.try(:valid_to)
+      self.valid_from_will_change!
+      self.valid_to_will_change!
+    end
+  end
+  
+  def recalculate_validity_range_from_direct_memberships!
+    unless direct?
+      self.valid_from_will_change!
+      self.valid_to_will_change!
+      recalculate_validity_range_from_direct_memberships
+      self.valid_from_will_change!
+      self.valid_to_will_change!
+      save!
+    else
+      raise "Recalculating the validity range makes only sense for indirect memberships. This is a direct one. Membership id: #{self.id}."
+    end
+  end
+  
+  def recalculate_indirect_validity_ranges_if_needed
+    if self.direct? and @need_to_recalculate_indirect_memberships == true
+      self.indirect_memberships.each do |indirect_membership|
+        indirect_membership.recalculate_validity_range_from_direct_memberships
+        indirect_membership.save
+      end
+    end
+  end
+  private :recalculate_indirect_validity_ranges_if_needed
+  
+
+
+  # Invalidation
+  # ====================================================================================================
+  
+  # For indirect memberships, invalidation is not possible.
+  # Only direct memberships can be invalidated. The validity of the indirect memberships
+  # inherts from the direct ones.
+  #
+  def make_invalid(time = Time.zone.now)
+    raise 'An indirect membership cannot be invalidated. ' + self.user.id.to_s + ' ' + self.group.id.to_s unless direct?
+    super
+  end
+  
+end

data/app/models/user_mixins/identification.rb

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+
+# This module extends the User class. Its purpose is to provide methods to identify a user using 
+# a given login string. The user may identify himself using his first name plus last name, his last name only, his 
+# email address or his alias, as long as the identifyer is unique.
+#
+module UserMixins::Identification
+
+  extend ActiveSupport::Concern
+
+  included do
+  end
+
+  module ClassMethods
+
+    # The user may identify himself using one of these attributes.
+    #
+    def attributes_used_for_identification
+      [ :alias, :last_name, :name, :email ]
+    end
+
+    # Find all users where the identification string matches one of the attributes
+    # given by `attributes_used_for_identification`.
+    #
+    # This method returns an array of users matching the given login string.
+    # In contrast to `self.identify`, this returns an array, whereas `self.identify`
+    # returns a user object if the match was unique.
+    #
+    def find_all_by_identification_string( identification_string )
+      self.attributes_used_for_identification.collect do |attribute_name|
+        self.send( "find_all_by_#{attribute_name}".to_sym, identification_string )
+      end.flatten.uniq
+    end
+
+  end
+end

data/app/models/user_mixins/memberships.rb

@@ -0,0 +1,75 @@
+# 
+# This module contains the methods of the User model regarding the associated 
+# user group memberships and groups.
+#
+module UserMixins::Memberships
+  
+  extend ActiveSupport::Concern
+  
+  # TODO: Refactor conditions to rails 4 standard when migrating to rails 4.
+  # See, for example, https://github.com/fiedl/neo4j_ancestry/blob/master/lib/models/neo4j_ancestry/active_record_additions.rb#L117.
+  
+  included do
+    
+    # User Group Memberships
+    # ==========================================================================================
+    
+    # This associates all UserGroupMembership objects of the group, including indirect 
+    # memberships.
+    #
+    has_many( :memberships, 
+              class_name: 'UserGroupMembership',
+              foreign_key: :descendant_id, conditions: { ancestor_type: 'Group', descendant_type: 'User' } )
+    
+    # This associates all memberships of the group that are direct, i.e. direct 
+    # parent_group-child_user memberships.
+    #
+    has_many( :direct_memberships,
+              class_name: 'UserGroupMembership', 
+              foreign_key: :descendant_id, conditions: { ancestor_type: 'Group', descendant_type: 'User', direct: true } )
+              
+    # This associates all memberships of the group that are indirect, i.e. 
+    # ancestor_group-descendant_user memberships, where groups are between the
+    # ancestor_group and the descendant_user.
+    #
+    has_many( :indirect_memberships,
+              class_name: 'UserGroupMembership', 
+              foreign_key: :descendant_id, conditions: { ancestor_type: 'Group', descendant_type: 'User', direct: false } )
+    
+    
+    # This returns the membership of the user in the given group if existant.
+    #
+    def membership_in( group )
+      memberships.where(ancestor_id: group.id).limit(1).first
+    end
+    
+    
+    # Groups the user is member of
+    # ==========================================================================================
+
+    # This associates the groups the user is member of, direct as well as indirect.
+    #
+    has_many(:groups, 
+      through: :memberships,
+      source: :ancestor, source_type: 'Group', :uniq => true,
+      conditions: { 'dag_links.descendant_type' => 'User' }
+      )
+
+    # This associates only the direct groups.
+    #
+    has_many(:direct_groups, 
+      through: :direct_memberships, 
+      source: :ancestor, source_type: 'Group', :uniq => true,
+      conditions: { 'dag_links.descendant_type' => 'User', 'dag_links.direct' => true }
+      )
+    
+    # This associates only the indirect groups.
+    #
+    has_many(:indirect_groups, 
+      through: :indirect_memberships, 
+      source: :ancestor, source_type: 'Group', :uniq => true,
+      conditions: { 'dag_links.descendant_type' => 'User', 'dag_links.direct' => false }
+      )
+    
+  end
+end