hold 1.0.0

data/lib/hold/sequel/property_mapper/foreign_key.rb

@@ -0,0 +1,96 @@
+module Hold::Sequel
+  # Maps to an associated object which is fetched by id from a target repository using a foriegn key column
+  class PropertyMapper::ForeignKey < PropertyMapper
+    def self.setter_dependencies_for(options={})
+      features = [*options[:model_class]].map {|klass| [:get_class, klass]}
+      {:target_repo => [Hold::IdentitySetRepository, *features]}
+    end
+
+    attr_accessor :target_repo
+
+    attr_reader :columns_aliases_and_tables_for_select, :column_alias, :column_name, :table,
+      :column_qualified, :auto_store_new, :model_class
+
+    # auto_store_new: where the value for this property is an object without an ID,
+    #  automatically store_new the object in the target_repo before trying to store
+    #  the object in question with this foreign key property. In the absence of this
+    #  setting, values without an ID will cause an exception
+    def initialize(repo, property_name, options)
+      super(repo, property_name)
+
+      @table = options[:table] || @repository.main_table
+      @column_name = options[:column_name] || :"#{property_name}_id"
+      @column_alias = :"#{@table}_#{@column_name}"
+      @column_qualified = Sequel::SQL::QualifiedIdentifier.new(@table, @column_name)
+      @columns_aliases_and_tables_for_select = [
+        [@column_qualified],
+        [Sequel::SQL::AliasedExpression.new(@column_qualified, @column_alias)],
+        [@table]
+      ]
+
+      @auto_store_new = options[:auto_store_new] || false
+      @model_class = options[:model_class] or raise ArgumentError
+    end
+
+    def load_value(row, id=nil, properties=nil)
+      fkey = row[@column_alias] and target_repo.get_by_id(fkey, :properties => properties)
+    end
+
+    def ensure_value_has_id_where_present(value)
+      if value && !value.id
+        if @auto_store_new
+          target_repo.store_new(value)
+        else
+          raise "value for ForeignKey mapped property #{@property_name} has no id, and :auto_store_new not specified"
+        end
+      end
+    end
+
+    def pre_insert(entity)
+      ensure_value_has_id_where_present(entity[@property_name])
+    end
+
+    def pre_update(entity, update_entity)
+      ensure_value_has_id_where_present(update_entity[@property_name])
+    end
+
+    def build_insert_row(entity, table, row, id=nil)
+      if @table == table && entity.has_key?(@property_name)
+        value = entity[@property_name]
+        row[@column_name] = value && value.id
+      end
+    end
+    alias :build_update_row :build_insert_row
+
+    # for now ignoring the columns_mapped_to, since Identity mapper is the only one
+    # for which this matters at present
+
+    def make_filter(value, columns_mapped_to=nil)
+      {@column_qualified => value && value.id}
+    end
+
+    def make_multi_filter(values, columns_mapped_to=nil)
+      {@column_qualified => values.map {|v| v.id}}
+    end
+
+    def make_filter_by_id(id, columns_mapped_to=nil)
+      {@column_qualified => id}
+    end
+
+    def make_filter_by_ids(ids, columns_mapped_to=nil)
+      {@column_qualified => ids}
+    end
+
+    # efficient batch load which takes advantage of get_many_by_ids on the target repo
+    def load_values(rows, ids=nil, properties=nil, &b)
+      fkeys = rows.map {|row| row[@column_alias]}
+      non_nil_fkeys = fkeys.compact
+      non_nil_fkey_results = if non_nil_fkeys.empty? then [] else
+        target_repo.get_many_by_ids(non_nil_fkeys, :properties => properties)
+      end
+      fkeys.each_with_index do |fkey, index|
+        yield(fkey ? non_nil_fkey_results.shift : nil, index)
+      end
+    end
+  end
+end

data/lib/hold/sequel/property_mapper/hash.rb

@@ -0,0 +1,60 @@
+module Hold::Sequel
+  # A property which is a hash of strings to other primitive values. Persisted 'all in one go'
+  # in a separate table.
+  class PropertyMapper::Hash < PropertyMapper
+    attr_reader :table, :foreign_key, :key_column, :value_column
+
+    def initialize(repo, property_name, options)
+      super(repo, property_name)
+
+      @table        = options[:table]        || :"#{repo.main_table}_#{property_name}"
+      @foreign_key  = options[:foreign_key]  || :"#{repo.main_table.to_s.singularize}_id"
+      @key_column   = options[:key_column]   || :key
+      @value_column = options[:value_column] || :value
+
+      @dataset    = @repository.db[@table]
+      @select_kv  = @repository.db[@table].select(
+        Sequel.as(@key_column,:key),
+        Sequel.as(@value_column,:value))
+      @select_all = @repository.db[@table].select(
+        Sequel.as(@key_column,:key),
+        Sequel.as(@value_column,:value),
+        Sequel.as(@foreign_key,:id))
+    end
+
+    def load_value(row=nil, id=nil, properties=nil)
+      result = {}
+      @select_kv.filter(@foreign_key => id).each do |row|
+        result[row[:key]] = row[:value]
+      end
+      result
+    end
+
+    def load_values(rows=nil, ids=nil, properties=nil, &block)
+      results = Hash.new {|h,k| h[k]={}}
+      @select_all.filter(@foreign_key => ids).each do |row|
+        results[row[:id]][row[:key]] = row[:value]
+      end
+      result.values_at(*ids).each_with_index(&block)
+    end
+
+    def pre_delete(entity)
+      @dataset.filter(@foreign_key => entity.id).delete
+    end
+
+    def post_insert(entity, rows, last_insert_id=nil)
+      hash = entity[@property_name] or return
+      @dataset.multi_insert(hash.map do |k,v|
+        {@foreign_key => last_insert_id, @key_column => k, @value_column => v}
+      end)
+    end
+
+    def post_update(entity, update_entity, rows, data_from_pre_update)
+      hash = update_entity[@property_name] or return
+      @dataset.filter(@foreign_key => entity.id).delete
+      @dataset.multi_insert(hash.map do |k,v|
+        {@foreign_key => entity.id, @key_column => k, @value_column => v}
+      end)
+    end
+  end
+end

data/lib/hold/sequel/property_mapper/identity.rb

@@ -0,0 +1,41 @@
+module Hold::Sequel
+  class PropertyMapper::Identity < PropertyMapper
+    def columns_aliases_and_tables_for_select(preferred_table=@repository.main_table)
+      qualified = qualified_column_name(preferred_table)
+      return [qualified], [qualified.as(:id)], [preferred_table]
+    end
+
+    def qualified_column_name(preferred_table=@repository.main_table)
+      id_column = @repository.table_id_column(preferred_table)
+      Sequel::SQL::QualifiedIdentifier.new(preferred_table, id_column)
+    end
+
+    # the ID needs to go into insert rows for /all/ tables of the repo
+    def build_insert_row(entity, table, row, id=nil)
+      id ||= entity[@property_name] or return
+      id_column = @repository.table_id_column(table)
+      row[id_column] = id
+    end
+
+    # we don't update the ID - considered immutable
+    def build_update_row(entity, table, row)
+    end
+
+    # After a successful insert, we assign the last_insert_id back onto the entity's id property:
+    def post_insert(entity, rows, last_insert_id=nil)
+      entity[@property_name] = last_insert_id if last_insert_id
+    end
+
+    def load_value(row, id=nil, version=nil)
+      row[:id]
+    end
+
+    def make_filter(value, columns_mapped_to)
+      {columns_mapped_to.first => value}
+    end
+
+    def make_multi_filter(values, columns_mapped_to)
+      {columns_mapped_to.first => values}
+    end
+  end
+end

data/lib/hold/sequel/property_mapper/many_to_many.rb

@@ -0,0 +1,158 @@
+module Hold::Sequel
+  # Maps to an array of associated objects stored in another repo, where a :join_table exists with columns for:
+  #   - our id property (:left_key)
+  #   - other repo's id property (:right_key)
+  #   - order position within the list, starting from 0 (:order_column)
+  #
+  # By default these properties aren't writeable - when they are writeable:
+  #
+  # (for now at least) the rows of the join table are owned and managed soley by the parent objects via this
+  # mapper. The associated objects themselves, however, are free-floating and are not touched during
+  # create/update/delete (except optionally to store_new any new ones on create of the parent object,
+  # when :auto_store_new => true).
+  #
+  # If you supply a hash as :filter, this will be used to filter the join table, and will also be merged
+  # into any rows inserted into the join table. So if you use it on a writeable property, it needs to be
+  # map columns just to values rather than to other sql conditions.
+  #
+  # NB: for now this does not assume (or do anything special with respect to) the presence of a reciprocal
+  #  many-to_many property on the target repo. This functionality will need adding later to help figure out
+  #  the side-effects of changes to a many-to-many property when it comes to cache invalidation, and to
+  #  ensure that the order given by the order_column is not upset by updates to the corresponding reciprocal
+  #  property.
+  #
+  # So:
+  #   - Rows are inserted into the join table after the parent object is created
+  #   - Rows in the join table are nuked and re-inserted after this property on the parent object is updated
+  #   - Rows in the join table are deleted before the parent object is deleted (unless :manual_cascade_delete
+  #     => false is specified hinting that ON CASCADE DELETE is set on the foreign key so we needn't bother)
+  class PropertyMapper::ManyToMany < PropertyMapper
+    def self.setter_dependencies_for(options={})
+      features = [*options[:model_class]].map {|klass| [:get_class, klass]}
+      {:target_repo => [IdentitySetRepository, *features]}
+    end
+
+    attr_accessor :target_repo
+
+    attr_reader :join_table, :left_key, :right_key, :order_column, :writeable,
+                :manual_cascade_delete, :auto_store_new, :distinct, :filter, :model_class
+
+    def initialize(repo, property_name, options, &block)
+      super(repo, property_name, &nil)
+
+      @join_table = options[:join_table] || :"#{repo.main_table}_#{property_name}"
+      @left_key   = options[:left_key]   || :"#{repo.main_table.to_s.singularize}_id"
+      @right_key  = options[:right_key]  || :"#{property_name.to_s.singularize}_id"
+      @qualified_left_key = Sequel::SQL::QualifiedIdentifier.new(@join_table, @left_key)
+      @qualified_right_key = Sequel::SQL::QualifiedIdentifier.new(@join_table, @right_key)
+
+      @filter = options[:filter]
+      @join_table_dataset = @repository.db[@join_table]
+      @distinct = options[:distinct] || false
+
+      @order_column = options[:order_column] and
+        @qualified_order_column = Sequel::SQL::QualifiedIdentifier.new(@join_table, @order_column)
+
+      @writeable = options[:writeable] || false
+      @manual_cascade_delete = options[:manual_cascade_delete] != false
+      @auto_store_new = options[:auto_store_new] || false
+
+      @model_class = options[:model_class] or raise ArgumentError
+
+      # in case you want to override anything on the instance:
+      instance_eval(&block) if block
+    end
+
+    def load_value(row, id, properties=nil)
+      target_repo.query(properties) do |dataset, property_columns|
+        id_column = property_columns[target_repo.identity_property].first
+        dataset = dataset.
+          join(@join_table, @qualified_right_key => id_column).
+          filter(@qualified_left_key => id)
+        dataset = dataset.filter(@filter) if @filter
+        dataset = dataset.distinct if @distinct
+        @qualified_order_column ? dataset.order(@qualified_order_column) : dataset
+      end.to_a
+    end
+
+    # efficient batch load for the non-lazy case
+    def load_values(rows, ids=nil, properties=nil, &b)
+      query = target_repo.query(properties) do |dataset, mapping|
+        id_column = mapping[target_repo.identity_property]
+        dataset = dataset
+          .join(@join_table, @qualified_right_key => id_column)
+          .filter(@qualified_left_key => ids)
+          .select(Sequel.as(@qualified_left_key,:_many_to_many_id))
+        dataset = dataset.filter(@filter) if @filter
+        dataset = dataset.distinct if @distinct
+        dataset = dataset.order(:_many_to_many_id, @qualified_order_column) if @qualified_order_column
+        dataset
+      end
+
+      groups = []; id_to_group = {}
+      ids.each_with_index {|id,index| id_to_group[id] = groups[index] = []}
+      query.results_with_rows.each do |entity, row|
+        id_to_group[row[:_many_to_many_id]] << entity
+      end
+      groups.each_with_index(&b)
+    end
+
+    # find all instances in this repo whose value for this property contains the given member instance
+    def get_many_by_member(member)
+      @repository.query do |dataset, property_columns|
+        id_column = property_columns[@repository.identity_property].first
+        dataset = dataset.
+          join(@join_table, @qualified_left_key => id_column).
+          filter(@qualified_right_key => member.id)
+        dataset = dataset.filter(@filter) if @filter
+        dataset = dataset.distinct if @distinct
+        dataset
+      end.to_a
+    end
+
+
+
+    def insert_join_table_rows(entity, id, values)
+      rows = []
+      values.each_with_index do |value, index|
+        value_id = value.id || if @auto_store_new
+          target_repo.store_new(value); value.id
+        else
+          raise "value for ManyToMany mapped property #{@property_name} has no id, and :auto_store_new not specified"
+        end
+        row = {@left_key => id, @right_key => value_id}
+        row[@order_column] = index if @order_column
+        row.merge!(@filter) if @filter
+        add_denormalized_columns_to_join_table_row(entity, value, row)
+        rows << row
+      end
+      @join_table_dataset.multi_insert(rows)
+    end
+
+    # this is a hook for you to override
+    def add_denormalized_columns_to_join_table_row(entity, value, row)
+    end
+
+    def delete_join_table_rows(id)
+      filters = {@left_key => id}
+      filters.merge!(@filter) if @filter
+      @join_table_dataset.filter(filters).delete
+    end
+
+    def post_insert(entity, rows, insert_id)
+      return unless @writeable
+      values = entity[@property_name] and insert_join_table_rows(entity, insert_id, values)
+    end
+
+    def post_update(entity, update_entity, rows, result_from_pre_update=nil)
+      return unless @writeable
+      update_values = update_entity[@property_name] or return
+      delete_join_table_rows(entity.id)
+      insert_join_table_rows(entity, entity.id, update_values)
+    end
+
+    def pre_delete(entity)
+      delete_join_table_rows(entity.id) if @manual_cascade_delete
+    end
+  end
+end

data/lib/hold/sequel/property_mapper/one_to_many.rb

@@ -0,0 +1,199 @@
+module Hold::Sequel
+  # Maps to an array of associated objects stored in another repo, which has a foreign_key-mapped
+  # property pointing at instances of our model class.
+  #
+  # By default these properties aren't writeable - when they are writeable, the values are treated
+  # like wholy-owned sub-components of the parent object.
+  #
+  # So, objects which are values of this property are:
+  #   - Created after the parent object is created
+  #   - Created/updated/deleted as appropriate after this property on the parent object is updated
+  #   - Deleted before the parent object is deleted (unless :manual_cascade_delete => false is
+  #     specified hinting that ON CASCADE DELETE is set on the foreign key so we needn't bother)
+  #
+  # On update:
+  # We allow you to re-order and/or update the existing values while maintaining their
+  # identities, remove some objects which were in the collection before (which get deleted) and possibly
+  # throw in new objects too (which get created), but you can't throw something in there which was
+  # previously attached to some other object, for the same reason that this doesn't fly on insert.
+  #
+  # If you specify a denormalized_count_column, this will be used to store the count of associated
+  # objects on a column on the main table of the parent object.
+  class PropertyMapper::OneToMany < PropertyMapper
+    def self.setter_dependencies_for(options={})
+      features = [*options[:model_class]].map {|klass| [:get_class, klass]}
+      {:target_repo => [IdentitySetRepository, *features]}
+    end
+
+    attr_accessor :target_repo
+
+    attr_reader :writeable, :manual_cascade_delete, :order_property, :order_direction,
+      :foreign_key_property_name, :denormalized_count_column, :model_class
+
+    def initialize(repo, property_name, options)
+      super(repo, property_name)
+
+      @foreign_key_property_name = options[:property] or raise "missing :property arg"
+      @order_property = options[:order_property]
+      @order_direction = options[:order_direction] || :asc
+
+      @extra_properties = {@foreign_key_property_name => true}
+      @extra_properties[@order_property] = true if @order_property
+
+      @writeable = options[:writeable] || false
+      @manual_cascade_delete = options[:manual_cascade_delete] != false
+
+      @denormalized_count_column = options[:denormalized_count_column]
+
+      @model_class = options[:model_class] or raise ArgumentError
+    end
+
+    def foreign_key_mapper
+      @foreign_key_mapper ||= begin
+        mapper = target_repo.mapper(@foreign_key_property_name)
+        unless mapper.is_a?(PropertyMapper::ForeignKey)
+          raise "OneToManyMapper: Expected ForeignKey mapper with name #{@foreign_key_property_name}"
+        end
+        unless mapper.target_repo.can_get_class?(@repository.model_class)
+          raise "OneToManyMapper: ForeignKey mapper's target repo #{mapper.target_repo.inspect} can't get our repository's model_class #{@repository.model_class}"
+        end
+        mapper
+      end
+    end
+
+    def load_value(row, id, properties=nil)
+      properties = (properties || target_repo.default_properties).merge(@extra_properties)
+      target_repo.query(properties) do |dataset, mapping|
+        filter = foreign_key_mapper.make_filter_by_id(id, mapping[@foreign_key_property_name])
+        dataset = dataset.filter(filter)
+        dataset = dataset.order(Sequel.send(@order_direction, @order_property)) if @order_property
+        dataset
+      end.to_a
+    end
+
+    def load_values(rows, ids=nil, properties=nil, &b)
+      properties = (properties || target_repo.default_properties).merge(@extra_properties)
+      query = target_repo.query(properties) do |dataset, mapping|
+        filter = foreign_key_mapper.make_filter_by_ids(ids, mapping[@foreign_key_property_name])
+        dataset = dataset
+          .filter(filter)
+          .select(foreign_key_mapper.column_qualified.as(:_one_to_many_id))
+
+        if @order_property
+          dataset = dataset.order(:_one_to_many_id, target_repo.mapper(@order_property).column_qualified.send(@order_direction))
+        end
+
+        dataset
+      end
+
+      groups = []; id_to_group = {}
+      ids.each_with_index {|id,index| id_to_group[id] = groups[index] = []}
+      query.results_with_rows.each do |entity, row|
+        id_to_group[row[:_one_to_many_id]] << entity
+      end
+      groups.each_with_index(&b)
+    end
+
+
+    # adds a join to the target_repo's table, onto a dataset from the mapper's repository.
+    def add_join(dataset)
+      # FIXME: doesn't take any care to pick a unique alias for the table when joining to it
+      # FIXME: doesn't use mapping to determine id_column
+      dataset.join(target_repo.table_name, foreign_key_mapper.column_name => @repository.identity_mapper.column_name)
+    end
+
+    # help the parent repo find instances whose value for this property contains a particular member.
+    # since we're one-to-many rather than many-to-many, this is relatively simple. we just get the foreign key
+    # property on the proposed member, see if it's set to anything, and if so if that thing exists within our repo.
+    # if it does then it's the only such object, because the member's foreign key can only point at one thing.
+    def get_many_by_member(member)
+      if member.has_key?(@foreign_key_property_name)
+        object = member[@foreign_key_property_name]
+        [object] if object && @repository.contains?(object) # we might not actually contain it
+      else
+        object = target_repo.get_property(member, @foreign_key_property_name)
+        [object] if object # we know we contain it since the target_repo's foreign_key_mapper has us as its target_repo
+      end
+    end
+
+
+    def build_insert_row(entity, table, row, id=nil)
+      return unless @denormalized_count_column && table == @repository.main_table
+      values = entity[@property_name]
+      row[@denormalized_count_column] = (values ? values.length : 0)
+    end
+
+    def post_insert(entity, rows, insert_id)
+      return unless @writeable
+
+      values = entity[@property_name] or return
+
+      # save the assocatied objects!
+      values.each_with_index do |value, index|
+        # if we allowed this you would potentially be detaching the object from its previous parent,
+        # but then we'd have to apply hooks etc to that object too, so rather avoid:
+        raise "OneToMany mapper for #{@property_name}: already-persisted values are not supported on insert" if value.id
+        set_foreign_key_and_order_properties_on_value(entity, value, index)
+        target_repo.store_new(value)
+      end
+    end
+
+    def set_foreign_key_and_order_properties_on_value(entity, value, index)
+      # ensure their corresponding foreign key mapped property points back at us
+      if (existing_value = value[@foreign_key_property_name])
+        # the associated object has a foreign key mapped property pointing at something else.
+        #
+        # we could have config to allow it to go and update the foreign key in cases like this, but could
+        # be messy in the presence of order columns etc.
+        raise "OneToMany mapper: one of the values for mapped property #{@property_name} has an existing \
+               value for the corresponding #{@foreign_key_property_name} property which is not equal \
+               to our good selves" unless existing_value == entity
+      else
+        value[@foreign_key_property_name] = entity
+      end
+
+      # ensure their order_property corresponds to their order in the array, at least for new members.
+      # (in an update, existing members may change order)
+      if @order_property == :position
+        if !value.id && (existing_index = value[@order_property])
+          raise "OneToMany mapper: one of the new values for mapped property #{@property_name} has an existing \
+                 value for the order property #{@order_property} property which is not equal to its index in \
+                 the array" unless existing_index == index
+        else
+          value[@order_property] = index
+        end
+      end
+    end
+
+    def pre_update(entity, update_entity)
+      # if an update is specified for this property, find out what the existing values are first:
+      load_value(nil, entity.id) if @writeable && update_entity[@property_name]
+    end
+
+    def build_update_row(entity, table, row, id=nil)
+      return unless @denormalized_count_column && table == @repository.main_table
+      values = entity[@property_name] and row[@denormalized_count_column] = values.length
+    end
+
+    def post_update(entity, update_entity, rows, values_before)
+      return unless @writeable
+      update_values = update_entity[@property_name] or return
+      # delete any values which are no longer around:
+      (values_before - update_values).each {|value| target_repo.delete(value)}
+      # insert any new ones / update any existing ones which remain:
+      update_values.each_with_index do |value, index|
+        raise "OneToMany mapper: already-persisted values are only allowed for property update where they \
+               were already a value of the property beforehand" if value.id && !values_before.include?(value)
+
+        set_foreign_key_and_order_properties_on_value(entity, value, index)
+        # this will insert any new values, or update any existing ones.
+        target_repo.store(value)
+      end
+    end
+
+    def pre_delete(entity)
+      return unless @manual_cascade_delete
+      load_value(nil, entity.id).each {|value| target_repo.delete(value)}
+    end
+  end
+end