dm-core 0.9.2

data/lib/dm-core/associations/one_to_one.rb

@@ -0,0 +1,61 @@
+module DataMapper
+  module Associations
+    module OneToOne
+      extend Assertions
+
+      # Setup one to one relationship between two models
+      # -
+      # @api private
+      def self.setup(name, model, options = {})
+        assert_kind_of 'name',    name,    Symbol
+        assert_kind_of 'model',   model,   Model
+        assert_kind_of 'options', options, Hash
+
+        repository_name = model.repository.name
+
+        model.class_eval <<-EOS, __FILE__, __LINE__
+          def #{name}
+            #{name}_association.first
+          end
+
+          def #{name}=(child_resource)
+            #{name}_association.replace(child_resource.nil? ? [] : [ child_resource ])
+          end
+
+          private
+
+          def #{name}_association
+            @#{name}_association ||= begin
+              unless relationship = model.relationships(#{repository_name.inspect})[:#{name}]
+                raise ArgumentError, 'Relationship #{name.inspect} does not exist'
+              end
+              association = Associations::OneToMany::Proxy.new(relationship, self)
+              parent_associations << association
+              association
+            end
+          end
+        EOS
+
+        model.relationships(repository_name)[name] = if options.has_key?(:through)
+          RelationshipChain.new(
+            :child_model              => options.fetch(:class_name, Extlib::Inflection.classify(name)),
+            :parent_model             => model.name,
+            :repository_name          => repository_name,
+            :near_relationship_name   => options[:through],
+            :remote_relationship_name => options.fetch(:remote_name, name),
+            :parent_key               => options[:parent_key],
+            :child_key                => options[:child_key]
+          )
+        else
+          Relationship.new(
+            Extlib::Inflection.underscore(Extlib::Inflection.demodulize(model.name)).to_sym,
+            repository_name,
+            options.fetch(:class_name, Extlib::Inflection.classify(name)),
+            model.name,
+            options
+          )
+        end
+      end
+    end # module HasOne
+  end # module Associations
+end # module DataMapper

data/lib/dm-core/associations/relationship.rb

@@ -0,0 +1,116 @@
+module DataMapper
+  module Associations
+    class Relationship
+      include Assertions
+
+      OPTIONS = [ :class_name, :child_key, :parent_key, :min, :max, :through ]
+
+      attr_reader :name, :repository_name, :options, :query
+
+      def child_key
+        @child_key ||= begin
+          model_properties = child_model.properties(repository_name)
+
+          child_key = parent_key.zip(@child_properties || []).map do |parent_property,property_name|
+            # TODO: use something similar to DM::NamingConventions to determine the property name
+            property_name ||= "#{name}_#{parent_property.name}".to_sym
+
+            model_properties[property_name] || DataMapper.repository(repository_name) do
+              attributes = {}
+
+              [ :length, :precision, :scale ].each do |attribute|
+                attributes[attribute] = parent_property.send(attribute)
+              end
+
+              # NOTE: hack to make each many to many child_key a true key,
+              # until I can figure out a better place for this check
+              if child_model.respond_to?(:many_to_many)
+                attributes[:key] = true
+              end
+
+              child_model.property(property_name, parent_property.primitive, attributes)
+            end
+          end
+          PropertySet.new(child_key)
+        end
+      end
+
+      def parent_key
+        @parent_key ||= begin
+          parent_key = if @parent_properties
+            parent_model.properties(repository_name).slice(*@parent_properties)
+          else
+            parent_model.key(repository_name)
+          end
+
+          PropertySet.new(parent_key)
+        end
+      end
+
+      def parent_model
+        Class === @parent_model ? @parent_model : self.class.find_const(@parent_model)
+      end
+
+      def child_model
+        Class === @child_model ? @child_model : self.class.find_const(@child_model)
+      end
+
+      # @api private
+      def get_children(parent, options = {}, finder = :all, *args)
+        bind_values = parent_key.get(parent)
+        return [] if bind_values.any? { |bind_value| bind_value.nil? }
+        query = child_key.to_query(bind_values)
+
+        DataMapper.repository(repository_name) do
+          child_model.send(finder, *(args << @query.merge(options).merge(query)))
+        end
+      end
+
+      # @api private
+      def get_parent(child)
+        bind_values = child_key.get(child)
+        return nil if bind_values.any? { |bind_value| bind_value.nil? }
+        query = parent_key.to_query(bind_values)
+
+        DataMapper.repository(repository_name) do
+          parent_model.first(@query.merge(query))
+        end
+      end
+
+      # @api private
+      def attach_parent(child, parent)
+        child_key.set(child, parent && parent_key.get(parent))
+      end
+
+      private
+
+      # +child_model_name and child_properties refers to the FK, parent_model_name
+      # and parent_properties refer to the PK.  For more information:
+      # http://edocs.bea.com/kodo/docs41/full/html/jdo_overview_mapping_join.html
+      # I wash my hands of it!
+      def initialize(name, repository_name, child_model, parent_model, options = {})
+        assert_kind_of 'name',              name,              Symbol
+        assert_kind_of 'repository_name',   repository_name,   Symbol
+        assert_kind_of 'child_model',  child_model,  String, Class
+        assert_kind_of 'parent_model', parent_model, String, Class
+
+        if child_properties = options[:child_key]
+          assert_kind_of 'options[:child_key]', child_properties, Array
+        end
+
+        if parent_properties = options[:parent_key]
+          assert_kind_of 'options[:parent_key]', parent_properties, Array
+        end
+
+        @name              = name
+        @repository_name   = repository_name
+        @child_model       = child_model
+        @child_properties  = child_properties   # may be nil
+        @query             = options.reject { |k,v| OPTIONS.include?(k) }
+        @parent_model      = parent_model
+        @parent_properties = parent_properties  # may be nil
+        @options           = options
+      end
+    end # class Relationship
+  end # module Associations
+end # module DataMapper

data/lib/dm-core/associations/relationship_chain.rb

@@ -0,0 +1,74 @@
+module DataMapper
+  module Associations
+    class RelationshipChain < Relationship
+      OPTIONS = [
+        :repository_name, :near_relationship_name, :remote_relationship_name,
+        :child_model, :parent_model, :parent_key, :child_key,
+        :min, :max
+      ]
+
+      undef_method :get_parent
+      undef_method :attach_parent
+
+      def child_model
+        near_relationship.child_model
+      end
+
+      # @api private
+      def get_children(parent, options = {}, finder = :all, *args)
+        query = @query.merge(options).merge(child_key.to_query(parent_key.get(parent)))
+
+        query[:links] = links
+
+        DataMapper.repository(parent.repository.name) do
+          results = grandchild_model.send(finder, *(args << query))
+          # FIXME: remove the need for the uniq.freeze
+          finder == :all ? (@mutable ? results.uniq : results.uniq.freeze) : results
+        end
+      end
+
+      private
+
+      def near_relationship
+        parent_model.relationships[@near_relationship_name]
+      end
+
+      def links
+        if remote_relationship.kind_of?(RelationshipChain)
+          remote_relationship.instance_eval { links } + [remote_relationship.instance_eval { near_relationship } ]
+        else
+          [ remote_relationship ]
+        end
+      end
+
+      def remote_relationship
+        near_relationship.child_model.relationships[@remote_relationship_name] ||
+          near_relationship.child_model.relationships[@remote_relationship_name.to_s.singularize.to_sym]
+      end
+
+      def grandchild_model
+        Class === @child_model ? @child_model : self.class.find_const(@child_model)
+      end
+
+      def initialize(options)
+        if (missing_options = OPTIONS - [ :min, :max ] - options.keys ).any?
+          raise ArgumentError, "The options #{missing_options * ', '} are required", caller
+        end
+
+        @repository_name          = options.fetch(:repository_name)
+        @near_relationship_name   = options.fetch(:near_relationship_name)
+        @remote_relationship_name = options.fetch(:remote_relationship_name)
+        @child_model              = options.fetch(:child_model)
+        @parent_model             = options.fetch(:parent_model)
+        @parent_properties        = options.fetch(:parent_key)
+        @child_properties         = options.fetch(:child_key)
+        @mutable                  = options.delete(:mutable) || false
+
+        @name        = near_relationship.name
+        @query       = options.reject{ |key,val| OPTIONS.include?(key) }
+        @extra_links = []
+        @options     = options
+      end
+    end # class Relationship
+  end # module Associations
+end # module DataMapper

data/lib/dm-core/auto_migrations.rb

@@ -0,0 +1,64 @@
+# TODO: move to dm-more/dm-migrations
+
+module DataMapper
+  class AutoMigrator
+    ##
+    # Destructively automigrates the data-store to match the model
+    # REPEAT: THIS IS DESTRUCTIVE
+    #
+    # @param Symbol repository_name the repository to be migrated
+    # @calls DataMapper::Resource#auto_migrate!
+    def self.auto_migrate(repository_name = nil)
+      DataMapper::Resource.descendants.each do |model|
+        model.auto_migrate!(repository_name)
+      end
+    end
+
+    ##
+    # Safely migrates the data-store to match the model
+    # preserving data already in the data-store
+    #
+    # @param Symbol repository_name the repository to be migrated
+    # @calls DataMapper::Resource#auto_upgrade!
+    def self.auto_upgrade(repository_name = nil)
+      DataMapper::Resource.descendants.each do |model|
+        model.auto_upgrade!(repository_name)
+      end
+    end
+  end # class AutoMigrator
+
+  module AutoMigrations
+    ##
+    # Destructively automigrates the data-store to match the model
+    # REPEAT: THIS IS DESTRUCTIVE
+    #
+    # @param Symbol repository_name the repository to be migrated
+    def auto_migrate!(repository_name = nil)
+      if self.superclass != Object
+        self.superclass.auto_migrate!(repository_name)
+      else
+        repository_name ||= default_repository_name
+        repository(repository_name) do |r|
+          (relationships(r.name)||{}).each_value { |relationship| relationship.child_key }
+          r.adapter.destroy_model_storage(r, self)
+          r.adapter.create_model_storage(r, self)
+        end
+      end
+    end
+
+    ##
+    # Safely migrates the data-store to match the model
+    # preserving data already in the data-store
+    #
+    # @param Symbol repository_name the repository to be migrated
+    def auto_upgrade!(repository_name = nil)
+      repository_name ||= default_repository_name
+      repository(repository_name) do |r|
+        (relationships(r.name)||{}).each_value { |relationship| relationship.child_key }
+        r.adapter.upgrade_model_storage(r, self)
+      end
+    end
+
+    Model.send(:include, self)
+  end # module AutoMigrations
+end # module DataMapper

data/lib/dm-core/collection.rb

@@ -0,0 +1,604 @@
+module DataMapper
+  class Collection < LazyArray
+    include Assertions
+
+    attr_reader :query
+
+    ##
+    # @return [Repository] the repository the collection is
+    #   associated with
+    #
+    # @api public
+    def repository
+      query.repository
+    end
+
+    ##
+    # loads the entries for the collection. Used by the
+    # adapters to load the instances of the declared
+    # model for this collection's query.
+    #
+    # @api private
+    def load(values)
+      add(model.load(values, query))
+    end
+
+    ##
+    # reloads the entries associated with this collection
+    #
+    # @param [DataMapper::Query] query (optional) additional query
+    #   to scope by.  Use this if you want to query a collections result
+    #   set
+    #
+    # @see DataMapper::Collection#all
+    #
+    # @api public
+    def reload(query = {})
+      @query = scoped_query(query)
+      @query.update(:fields => @query.fields | @key_properties)
+      replace(all(:reload => true))
+    end
+
+    ##
+    # retrieves an entry out of the collection's entry by key
+    #
+    # @param [DataMapper::Types::*, ...] key keys which uniquely
+    #   identify a resource in the collection
+    #
+    # @return [DataMapper::Resource, NilClass] the resource which
+    #   has the supplied keys
+    #
+    # @api public
+    def get(*key)
+      if loaded?
+        # loop over the collection to find the matching resource
+        detect { |resource| resource.key == key }
+      elsif query.limit || query.offset > 0
+        # current query is exclusive, find resource within the set
+
+        # TODO: use a subquery to retrieve the collection and then match
+        #   it up against the key.  This will require some changes to
+        #   how subqueries are generated, since the key may be a
+        #   composite key.  In the case of DO adapters, it means subselects
+        #   like the form "(a, b) IN(SELECT a,b FROM ...)", which will
+        #   require making it so the Query condition key can be a
+        #   Property or an Array of Property objects
+
+        # use the brute force approach until subquery lookups work
+        lazy_load
+        get(*key)
+      else
+        # current query is all inclusive, lookup using normal approach
+        first(model.to_query(repository, key))
+      end
+    end
+
+    ##
+    # retrieves an entry out of the collection's entry by key,
+    # raising an exception if the object cannot be found
+    #
+    # @param [DataMapper::Types::*, ...] key keys which uniquely
+    #   identify a resource in the collection
+    #
+    # @calls DataMapper::Collection#get
+    #
+    # @raise [ObjectNotFoundError] "Could not find #{model.name} with key #{key.inspect} in collection"
+    #
+    # @api public
+    def get!(*key)
+      get(*key) || raise(ObjectNotFoundError, "Could not find #{model.name} with key #{key.inspect} in collection")
+    end
+
+    ##
+    # Further refines a collection's conditions.  #all provides an
+    # interface which simulates a database view.
+    #
+    # @param [Hash[Symbol, Object], DataMapper::Query] query parameters for
+    #   an query within the results of the original query.
+    #
+    # @return [DataMapper::Collection] a collection whose query is the result
+    #   of a merge
+    #
+    # @api public
+    def all(query = {})
+      # TODO: this shouldn't be a kicker if scoped_query() is called
+      return self if query.kind_of?(Hash) ? query.empty? : query == self.query
+      query = scoped_query(query)
+      query.repository.read_many(query)
+    end
+
+    ##
+    # Simulates Array#first by returning the first entry (when
+    # there are no arguments), or transforms the collection's query
+    # by applying :limit => n when you supply an Integer. If you
+    # provide a conditions hash, or a Query object, the internal
+    # query is scoped and a new collection is returned
+    #
+    # @param [Integer, Hash[Symbol, Object], Query] args
+    #
+    # @return [DataMapper::Resource, DataMapper::Collection] The
+    #   first resource in the entries of this collection, or
+    #   a new collection whose query has been merged
+    #
+    # @api public
+    def first(*args)
+      # TODO: this shouldn't be a kicker if scoped_query() is called
+      if loaded?
+        if args.empty?
+          return super
+        elsif args.size == 1 && args.first.kind_of?(Integer)
+          limit = args.shift
+          return self.class.new(scoped_query(:limit => limit)) { |c| c.replace(super(limit)) }
+        end
+      end
+
+      query = args.last.respond_to?(:merge) ? args.pop : {}
+      query = scoped_query(query.merge(:limit => args.first || 1))
+
+      if args.any?
+        query.repository.read_many(query)
+      else
+        query.repository.read_one(query)
+      end
+    end
+
+    ##
+    # Simulates Array#last by returning the last entry (when
+    # there are no arguments), or transforming the collection's
+    # query by reversing the declared order, and applying
+    # :limit => n when you supply an Integer.  If you
+    # supply a conditions hash, or a Query object, the
+    # internal query is scoped and a new collection is returned
+    #
+    # @calls Collection#first
+    #
+    # @api public
+    def last(*args)
+      return super if loaded? && args.empty?
+
+      reversed = reverse
+
+      # tell the collection to reverse the order of the
+      # results coming out of the adapter
+      reversed.query.add_reversed = !query.add_reversed?
+
+      reversed.first(*args)
+    end
+
+    ##
+    # Simulates Array#at and returns the entrie at that index.
+    # Also accepts negative indexes and appropriate reverses
+    # the order of the query
+    #
+    # @calls Collection#first
+    # @calls Collection#last
+    #
+    # @api public
+    def at(offset)
+      return super if loaded?
+      offset >= 0 ? first(:offset => offset) : last(:offset => offset.abs - 1)
+    end
+
+    ##
+    # Simulates Array#slice and returns a new Collection
+    # whose query has a new offset or limit according to the
+    # arguments provided.
+    #
+    # If you provide a range, the min is used as the offset
+    # and the max minues the offset is used as the limit.
+    #
+    # @param [Integer, Array(Integer), Range] args the offset,
+    # offset and limit, or range indicating offsets and limits
+    #
+    # @return [DataMapper::Resource, DataMapper::Collection]
+    #   The entry which resides at that offset and limit,
+    #   or a new Collection object with the set limits and offset
+    #
+    # @raise [ArgumentError] "arguments may be 1 or 2 Integers,
+    #   or 1 Range object, was: #{args.inspect}"
+    #
+    # @alias []
+    #
+    # @api public
+    def slice(*args)
+      return at(args.first) if args.size == 1 && args.first.kind_of?(Integer)
+
+      if args.size == 2 && args.first.kind_of?(Integer) && args.last.kind_of?(Integer)
+        offset, limit = args
+      elsif args.size == 1 && args.first.kind_of?(Range)
+        range  = args.first
+        offset = range.first
+        limit  = range.last - offset
+        limit += 1 unless range.exclude_end?
+      else
+        raise ArgumentError, "arguments may be 1 or 2 Integers, or 1 Range object, was: #{args.inspect}", caller
+      end
+
+      all(:offset => offset, :limit => limit)
+    end
+
+    alias [] slice
+
+    ##
+    #
+    # @return [DataMapper::Collection] a new collection whose
+    #   query is sorted in the reverse
+    #
+    # @see Array#reverse, DataMapper#all, DataMapper::Query#reverse
+    #
+    # @api public
+    def reverse
+      all(self.query.reverse)
+    end
+
+    ##
+    # @see Array#<<
+    #
+    # @api public
+    def <<(resource)
+      super
+      relate_resource(resource)
+      self
+    end
+
+    ##
+    # @see Array#push
+    #
+    # @api public
+    def push(*resources)
+      super
+      resources.each { |resource| relate_resource(resource) }
+      self
+    end
+
+    ##
+    # @see Array#unshift
+    #
+    # @api public
+    def unshift(*resources)
+      super
+      resources.each { |resource| relate_resource(resource) }
+      self
+    end
+
+    ##
+    # @see Array#replace
+    #
+    # @api public
+    def replace(other)
+      if loaded?
+        each { |resource| orphan_resource(resource) }
+      end
+      super
+      other.each { |resource| relate_resource(resource) }
+      self
+    end
+
+    ##
+    # @see Array#pop
+    #
+    # @api public
+    def pop
+      orphan_resource(super)
+    end
+
+    ##
+    # @see Array#shift
+    #
+    # @api public
+    def shift
+      orphan_resource(super)
+    end
+
+    ##
+    # @see Array#delete
+    #
+    # @api public
+    def delete(resource, &block)
+      orphan_resource(super)
+    end
+
+    ##
+    # @see Array#delete_at
+    #
+    # @api public
+    def delete_at(index)
+      orphan_resource(super)
+    end
+
+    ##
+    # @see Array#clear
+    #
+    # @api public
+    def clear
+      if loaded?
+        each { |resource| orphan_resource(resource) }
+      end
+      super
+      self
+    end
+
+    ##
+    # creates a new array, saves it, and << it onto the collection
+    #
+    # @param Hash[Symbol => Object] attributes attributes which
+    #   the new resource should have.
+    #
+    # @api public
+    def create(attributes = {})
+      repository.scope do
+        resource = model.create(default_attributes.merge(attributes))
+        self << resource unless resource.new_record?
+        resource
+      end
+    end
+
+    def update(attributes = {}, preload = false)
+      raise NotImplementedError, 'update *with* validations has not be written yet, try update!'
+    end
+
+    ##
+    # batch updates the entries belongs to this collection, and skip
+    # validations for all resources.
+    #
+    # @example Reached the Age of Alchohol Consumption
+    #   Person.all(:age.gte => 21).update!(:allow_beer => true)
+    #
+    # @param attributes Hash[Symbol => Object] attributes to update
+    # @param reload [FalseClass, TrueClass] if set to true, collection
+    #   will have loaded resources reflect updates.
+    #
+    # @return [TrueClass, FalseClass]
+    #   TrueClass indicates that all entries were affected
+    #   FalseClass indicates that some entries were affected
+    #
+    # @api public
+    def update!(attributes = {}, reload = false)
+      # TODO: delegate to Model.update
+      return true if attributes.empty?
+
+      dirty_attributes = {}
+
+      model.properties(repository.name).slice(*attributes.keys).each do |property|
+        dirty_attributes[property] = attributes[property.name] if property
+      end
+
+      # this should never be done on update! even if collection is loaded. or?
+      # each { |resource| resource.attributes = attributes } if loaded?
+
+      changes = repository.update(dirty_attributes, scoped_query)
+
+      # need to decide if this should be done in update!
+      query.update(attributes)
+
+      if identity_map.any? && reload
+        reload_query = @key_properties.zip(identity_map.keys.transpose).to_hash
+        model.all(reload_query.merge(attributes)).reload(:fields => attributes.keys)
+      end
+
+      # this should return true if there are any changes at all. as it skips validations
+      # the only way it could be fewer changes is if some resources already was updated.
+      # that should not return false? true = 'now all objects have these new values'
+      return loaded? ? changes == size : changes > 0
+    end
+
+    def destroy
+      raise NotImplementedError, 'destroy *with* validations has not be written yet, try destroy!'
+    end
+
+    ##
+    # batch destroy the entries belongs to this collection, and skip
+    # validations for all resources.
+    #
+    # @example The War On Terror (if only it were this easy)
+    #   Person.all(:terrorist => true).destroy() #
+    #
+    # @return [TrueClass, FalseClass]
+    #   TrueClass indicates that all entries were affected
+    #   FalseClass indicates that some entries were affected
+    #
+    # @api public
+    def destroy!
+      # TODO: delegate to Model.destroy
+      if loaded?
+        return false unless repository.delete(scoped_query) == size
+
+        each do |resource|
+          resource.instance_variable_set(:@new_record, true)
+          identity_map.delete(resource.key)
+          resource.dirty_attributes.clear
+
+          model.properties(repository.name).each do |property|
+            next unless resource.attribute_loaded?(property.name)
+            resource.dirty_attributes[property] = property.get(resource)
+          end
+        end
+      else
+        return false unless repository.delete(scoped_query) > 0
+      end
+
+      clear
+
+      true
+    end
+
+    ##
+    # @return [DataMapper::PropertySet] The set of properties this
+    #   query will be retrieving
+    #
+    # @api public
+    def properties
+      PropertySet.new(query.fields)
+    end
+
+    ##
+    # @return [DataMapper::Relationship] The model's relationships
+    #
+    # @api public
+    def relationships
+      model.relationships(repository.name)
+    end
+
+    ##
+    # default values to use when creating a Resource within the Collection
+    #
+    # @return [Hash] The default attributes for DataMapper::Collection#create
+    #
+    # @see DataMapper::Collection#create
+    #
+    # @api public
+    def default_attributes
+      default_attributes = {}
+      query.conditions.each do |tuple|
+        operator, property, bind_value = *tuple
+
+        next unless operator == :eql &&
+          property.kind_of?(DataMapper::Property) &&
+          ![ Array, Range ].any? { |k| bind_value.kind_of?(k) }
+          !@key_properties.include?(property)
+
+        default_attributes[property.name] = bind_value
+      end
+      default_attributes
+    end
+
+    protected
+
+    ##
+    # @api private
+    #
+    # @api public
+    def model
+      query.model
+    end
+
+    private
+
+    ##
+    # @api public
+    def initialize(query, &block)
+      assert_kind_of 'query', query, Query
+
+      unless block_given?
+        raise ArgumentError, 'a block must be supplied for lazy loading results', caller
+      end
+
+      @query          = query
+      @key_properties = model.key(repository.name)
+
+      super()
+
+      load_with(&block)
+    end
+
+    ##
+    # @api private
+    def add(resource)
+      query.add_reversed? ? unshift(resource) : push(resource)
+      resource
+    end
+
+    ##
+    # @api private
+    def relate_resource(resource)
+      return unless resource
+      resource.collection = self
+      resource
+    end
+
+    ##
+    # @api private
+    def orphan_resource(resource)
+      return unless resource
+      resource.collection = nil if resource.collection == self
+      resource
+    end
+
+    ##
+    # @api private
+    def scoped_query(query = self.query)
+      assert_kind_of 'query', query, Query, Hash
+
+      query.update(keys) if loaded?
+
+      return self.query if query == self.query
+
+      query = if query.kind_of?(Hash)
+        Query.new(query.has_key?(:repository) ? query.delete(:repository) : self.repository, model, query)
+      else
+        query
+      end
+
+      if query.limit || query.offset > 0
+        set_relative_position(query)
+      end
+
+      self.query.merge(query)
+    end
+
+    ##
+    # @api private
+    def keys
+      keys = map {|r| r.key }
+      keys.any? ? @key_properties.zip(keys.transpose).to_hash : {}
+    end
+
+    ##
+    # @api private
+    def identity_map
+      repository.identity_map(model)
+    end
+
+    ##
+    # @api private
+    def set_relative_position(query)
+      return if query == self.query
+
+      if query.offset == 0
+        return if !query.limit.nil? && !self.query.limit.nil? && query.limit <= self.query.limit
+        return if  query.limit.nil? &&  self.query.limit.nil?
+      end
+
+      first_pos = self.query.offset + query.offset
+      last_pos  = self.query.offset + self.query.limit if self.query.limit
+
+      if limit = query.limit
+        if last_pos.nil? || first_pos + limit < last_pos
+          last_pos = first_pos + limit
+        end
+      end
+
+      if last_pos && first_pos >= last_pos
+        raise 'outside range'  # TODO: raise a proper exception object
+      end
+
+      query.update(:offset => first_pos)
+      query.update(:limit => last_pos - first_pos) if last_pos
+    end
+
+    ##
+    # @api private
+    def method_missing(method, *args, &block)
+      if relationship = relationships[method]
+        klass = model == relationship.child_model ? relationship.parent_model : relationship.child_model
+
+        # TODO: when self.query includes an offset/limit use it as a
+        # subquery to scope the results rather than a join
+
+        query = Query.new(repository, klass)
+        query.conditions.push(*self.query.conditions)
+        query.update(relationship.query)
+        query.update(args.pop) if args.last.kind_of?(Hash)
+
+        query.update(
+          :fields => klass.properties(repository.name).defaults,
+          :links  => self.query.links + [ relationship ]
+        )
+
+        return klass.all(query, &block)
+      end
+
+      super
+    end
+  end # class Collection
+end # module DataMapper