dm-core 0.9.11 → 0.10.0

data/lib/dm-core/model.rb

@@ -1,316 +1,421 @@
-require 'set'
+# TODO: add Model#create!, Model#update, Model#update!, Model#destroy and Model#destroy!
 
 module DataMapper
   module Model
-    ##
-    #
-    # Extends the model with this module after DataMapper::Resource has been
-    # included.
+    extend Chainable
+
+    # Creates a new Model class with default_storage_name +storage_name+
     #
-    # This is a useful way to extend DataMapper::Model while
-    # still retaining a self.extended method.
+    # If a block is passed, it will be eval'd in the context of the new Model
     #
-    # @param [Module] extensions the module that is to be extend the model after
-    #   after DataMapper::Model
+    # @param [Proc] block
+    #   a block that will be eval'd in the context of the new Model class
     #
-    # @return [TrueClass, FalseClass] whether or not the inclusions have been
-    #   successfully appended to the list
-    #-
-    # @api public
+    # @return [Model]
+    #   the newly created Model class
     #
-    # TODO: Move this do DataMapper::Model when DataMapper::Model is created
-    def self.append_extensions(*extensions)
-      extra_extensions.concat extensions
-      true
-    end
-
-    def self.extra_extensions
-      @extra_extensions ||= []
-    end
-
-    def self.extended(model)
-      model.instance_variable_set(:@storage_names, {})
-      model.instance_variable_set(:@properties,    {})
-      model.instance_variable_set(:@field_naming_conventions, {})
-      extra_extensions.each { |extension| model.extend(extension) }
-    end
+    # @api semipublic
+    def self.new(storage_name = nil, &block)
+      model = Class.new
 
-    def inherited(target)
-      target.instance_variable_set(:@storage_names,       @storage_names.dup)
-      target.instance_variable_set(:@properties,          {})
-      target.instance_variable_set(:@base_model,          self.base_model)
-      target.instance_variable_set(:@paranoid_properties, @paranoid_properties)
-      target.instance_variable_set(:@field_naming_conventions,  @field_naming_conventions.dup)
+      model.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        include DataMapper::Resource
 
-      if self.respond_to?(:validators)
-        @validations.contexts.each do |context, validators|
-          validators.each { |validator| target.validators.context(context) << validator }
+        def self.name
+          to_s
         end
-      end
+      RUBY
 
-      @properties.each do |repository_name,properties|
-        repository(repository_name) do
-          properties.each do |property|
-            next if target.properties(repository_name).has_property?(property.name)
-            target.property(property.name, property.type, property.options.dup)
+      if storage_name
+        warn "Passing in +storage_name+ to #{name}.new is deprecated (#{caller[0]})"
+        model.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def self.default_storage_name
+            #{Extlib::Inflection.classify(storage_name).inspect}.freeze
           end
-        end
+        RUBY
       end
 
-      if @relationships
-        duped_relationships = {}
-        @relationships.each do |repository_name,relationships|
-          relationships.each do |name, relationship|
-            dup = relationship.dup
-            dup.instance_variable_set(:@child_model, target) if dup.instance_variable_get(:@child_model) == self
-            dup.instance_variable_set(:@parent_model, target) if dup.instance_variable_get(:@parent_model) == self
-            duped_relationships[repository_name] ||= {}
-            duped_relationships[repository_name][name] = dup
-          end
-        end
-        target.instance_variable_set(:@relationships, duped_relationships)
-      end
-    end
-
-    def self.new(storage_name, &block)
-      model = Class.new
-      model.send(:include, Resource)
-      model.class_eval <<-EOS, __FILE__, __LINE__
-        def self.default_storage_name
-          #{Extlib::Inflection.classify(storage_name).inspect}
-        end
-      EOS
-      model.instance_eval(&block) if block_given?
+      model.instance_eval(&block) if block
       model
     end
 
-    def base_model
-      @base_model ||= self
-    end
-
-    def repository_name
-      Repository.context.any? ? Repository.context.last.name : default_repository_name
+    # Return all models that extend the Model module
+    #
+    #   class Foo
+    #     include DataMapper::Resource
+    #   end
+    #
+    #   DataMapper::Model.descendants.first   #=> Foo
+    #
+    # @return [DescendantSet]
+    #   Set containing the descendant models
+    #
+    # @api private
+    def self.descendants
+      @descendants ||= DescendantSet.new
     end
 
-    ##
-    # Get the repository with a given name, or the default one for the current
-    # context, or the default one for this class.
+    # Return all models that inherit from a Model
     #
-    # @param name<Symbol>   the name of the repository wanted
-    # @param block<Block>   block to execute with the fetched repository as parameter
+    #   class Foo
+    #     include DataMapper::Resource
+    #   end
     #
-    # @return <Object, DataMapper::Respository> whatever the block returns,
-    #   if given a block, otherwise the requested repository.
-    #-
-    # @api public
-    def repository(name = nil)
-      #
-      # There has been a couple of different strategies here, but me (zond) and dkubb are at least
-      # united in the concept of explicitness over implicitness. That is - the explicit wish of the
-      # caller (+name+) should be given more priority than the implicit wish of the caller (Repository.context.last).
-      #
-      if block_given?
-        DataMapper.repository(name || repository_name) { |*block_args| yield(*block_args) }
-      else
-        DataMapper.repository(name || repository_name)
-      end
-    end
+    #   class Bar < Foo
+    #   end
+    #
+    #   Foo.descendants.first   #=> Bar
+    #
+    # @return [Set]
+    #   Set containing the descendant classes
+    #
+    # @api private
+    attr_reader :descendants
 
-    ##
-    # the name of the storage recepticle for this resource.  IE. table name, for database stores
+    # Appends a module for inclusion into the model class after Resource.
     #
-    # @return <String> the storage name (IE table name, for database stores) associated with this resource in the given repository
-    def storage_name(repository_name = default_repository_name)
-      @storage_names[repository_name] ||= repository(repository_name).adapter.resource_naming_convention.call(base_model.send(:default_storage_name))
+    # This is a useful way to extend Resource while still retaining a
+    # self.included method.
+    #
+    # @param [Module] inclusions
+    #   the module that is to be appended to the module after Resource
+    #
+    # @return [Boolean]
+    #   true if the inclusions have been successfully appended to the list
+    #
+    # @api semipublic
+    def self.append_inclusions(*inclusions)
+      extra_inclusions.concat inclusions
+      true
     end
 
-    ##
-    # the names of the storage recepticles for this resource across all repositories
+    # The current registered extra inclusions
     #
-    # @return <Hash(Symbol => String)> All available names of storage recepticles
-    def storage_names
-      @storage_names
+    # @return [Set]
+    #
+    # @api private
+    def self.extra_inclusions
+      @extra_inclusions ||= []
     end
 
-    ##
-    # The field naming conventions for this resource across all repositories.
+    # Extends the model with this module after Resource has been included.
     #
-    # @return <String> The naming convention for the given repository
-    def field_naming_convention(repository_name = default_storage_name)
-      @field_naming_conventions[repository_name] ||= repository(repository_name).adapter.field_naming_convention
+    # This is a useful way to extend Model while still retaining a self.extended method.
+    #
+    # @param [Module] extensions
+    #   List of modules that will extend the model after it is extended by Model
+    #
+    # @return [Boolean]
+    #   whether or not the inclusions have been successfully appended to the list
+    #
+    # @api semipublic
+    def self.append_extensions(*extensions)
+      extra_extensions.concat extensions
+      true
     end
 
-    ##
-    # defines a property on the resource
+    # The current registered extra extensions
     #
-    # @param <Symbol> name the name for which to call this property
-    # @param <Type> type the type to define this property ass
-    # @param <Hash(Symbol => String)> options a hash of available options
-    # @see DataMapper::Property
-    def property(name, type, options = {})
-      property = Property.new(self, name, type, options)
-
-      create_property_getter(property)
-      create_property_setter(property)
-
-      properties(repository_name)[property.name] = property
-      @_valid_relations = false
+    # @return [Set]
+    #
+    # @api private
+    def self.extra_extensions
+      @extra_extensions ||= []
+    end
 
-      # Add property to the other mappings as well if this is for the default
-      # repository.
-      if repository_name == default_repository_name
-        @properties.each_pair do |repository_name, properties|
-          next if repository_name == default_repository_name
-          properties << property unless properties.has_property?(property.name)
-        end
-      end
+    # TODO: document
+    # @api private
+    def self.extended(model)
+      descendants << model
 
-      # Add the property to the lazy_loads set for this resources repository
-      # only.
-      # TODO Is this right or should we add the lazy contexts to all
-      # repositories?
-      if property.lazy?
-        context = options.fetch(:lazy, :default)
-        context = :default if context == true
+      model.instance_variable_set(:@valid,         false)
+      model.instance_variable_set(:@base_model,    model)
+      model.instance_variable_set(:@storage_names, {})
+      model.instance_variable_set(:@default_order, {})
+      model.instance_variable_set(:@descendants,   descendants.class.new(model, descendants))
 
-        Array(context).each do |item|
-          properties(repository_name).lazy_context(item) << name
-        end
-      end
+      extra_extensions.each { |mod| model.extend(mod)         }
+      extra_inclusions.each { |mod| model.send(:include, mod) }
+    end
 
-      # add the property to the child classes only if the property was
-      # added after the child classes' properties have been copied from
-      # the parent
-      if respond_to?(:descendants)
-        descendants.each do |model|
-          next if model.properties(repository_name).has_property?(name)
-          model.property(name, type, options)
+    # TODO: document
+    # @api private
+    chainable do
+      def inherited(model)
+        descendants << model
+
+        model.instance_variable_set(:@valid,         false)
+        model.instance_variable_set(:@base_model,    base_model)
+        model.instance_variable_set(:@storage_names, @storage_names.dup)
+        model.instance_variable_set(:@default_order, @default_order.dup)
+        model.instance_variable_set(:@descendants,   descendants.class.new(model, descendants))
+
+        # TODO: move this into dm-validations
+        if respond_to?(:validators)
+          validators.contexts.each do |context, validators|
+            model.validators.context(context).concat(validators)
+          end
         end
       end
-
-      property
     end
 
-    def repositories
-      [ repository ].to_set + @properties.keys.collect { |repository_name| DataMapper.repository(repository_name) }
+    # Gets the name of the storage receptacle for this resource in the given
+    # Repository (ie., table name, for database stores).
+    #
+    # @return [String]
+    #   the storage name (ie., table name, for database stores) associated with
+    #   this resource in the given repository
+    #
+    # @api public
+    def storage_name(repository_name = default_repository_name)
+      storage_names[repository_name] ||= repository(repository_name).adapter.resource_naming_convention.call(default_storage_name).freeze
     end
 
-    def properties(repository_name = default_repository_name)
-      # We need to check whether all relations are already set up.
-      # If this isn't the case, we try to reload them here
-      if !@_valid_relations && respond_to?(:many_to_one_relationships)
-        @_valid_relations = true
-        begin
-          many_to_one_relationships.each do |r|
-            r.child_key
-          end
-        rescue NameError
-          # Apparently not all relations are loaded,
-          # so we will try again later on
-          @_valid_relations = false
-        end
-      end
-      @properties[repository_name] ||= repository_name == Repository.default_name ? PropertySet.new : properties(Repository.default_name).dup
+    # the names of the storage receptacles for this resource across all repositories
+    #
+    # @return [Hash(Symbol => String)]
+    #   All available names of storage recepticles
+    #
+    # @api public
+    def storage_names
+      @storage_names
     end
 
-    def eager_properties(repository_name = default_repository_name)
-      properties(repository_name).defaults
-    end
+    # Grab a single record by its key. Supports natural and composite key
+    # lookups as well.
+    #
+    #   Zoo.get(1)                # get the zoo with primary key of 1.
+    #   Zoo.get!(1)               # Or get! if you want an ObjectNotFoundError on failure
+    #   Zoo.get('DFW')            # wow, support for natural primary keys
+    #   Zoo.get('Metro', 'DFW')   # more wow, composite key look-up
+    #
+    # @param [Object] *key
+    #   The primary key or keys to use for lookup
+    #
+    # @return [Resource,NilClass]
+    #   A single model that was found
+    #   If no instance was found matching +key+
+    #
+    # @api public
+    def get(*key)
+      repository = self.repository
+      key        = self.key(repository.name).typecast(key)
 
-    # @api private
-    def properties_with_subclasses(repository_name = default_repository_name)
-      properties = PropertySet.new
-      ([ self ].to_set + (respond_to?(:descendants) ? descendants : [])).each do |model|
-        model.relationships(repository_name).each_value { |relationship| relationship.child_key }
-        model.many_to_one_relationships.each do |relationship| relationship.child_key end
-        model.properties(repository_name).each do |property|
-          properties << property unless properties.has_property?(property.name)
-        end
-      end
-      properties
+      repository.identity_map(self)[key] || first(key_conditions(repository, key))
     end
 
-    def key(repository_name = default_repository_name)
-      properties(repository_name).key
+    # Grab a single record just like #get, but raise an ObjectNotFoundError
+    # if the record doesn't exist.
+    #
+    # @param [Object] *key
+    #   The primary key or keys to use for lookup
+    # @return [Resource]
+    #   A single model that was found
+    # @raise [ObjectNotFoundError]
+    #   The record was not found
+    #
+    # @api public
+    def get!(*key)
+      get(*key) || raise(ObjectNotFoundError, "Could not find #{self.name} with key #{key.inspect}")
     end
 
-    def inheritance_property(repository_name = default_repository_name)
-      @properties[repository_name].detect { |property| property.type == DataMapper::Types::Discriminator }
+    def [](*args)
+      all[*args]
     end
 
-    def default_order(repository_name = default_repository_name)
-      @default_order ||= {}
-      @default_order[repository_name] ||= key(repository_name).map { |property| Query::Direction.new(property) }
+    alias slice []
+
+    def at(*args)
+      all.at(*args)
     end
 
-    def get(*key)
-      key = typecast_key(key)
-      repository.identity_map(self).get(key) || first(to_query(repository, key))
+    def reverse
+      all.reverse
     end
 
-    def get!(*key)
-      get(*key) || raise(ObjectNotFoundError, "Could not find #{self.name} with key #{key.inspect}")
+    # TODO: spec this
+    def entries
+      all.entries
     end
 
-    def all(query = {})
-      query = scoped_query(query)
-      query.repository.read_many(query)
+    alias to_a entries
+
+    # Find a set of records matching an optional set of conditions. Additionally,
+    # specify the order that the records are return.
+    #
+    #   Zoo.all                                   # all zoos
+    #   Zoo.all(:open => true)                    # all zoos that are open
+    #   Zoo.all(:opened_on => start..end)         # all zoos that opened on a date in the date-range
+    #   Zoo.all(:order => [ :tiger_count.desc ])  # Ordered by tiger_count
+    #
+    # @param [Hash] query
+    #   A hash describing the conditions and order for the query
+    # @return [Collection]
+    #   A set of records found matching the conditions in +query+
+    # @see Collection
+    #
+    # @api public
+    def all(query = nil)
+      if query.nil? || (query.kind_of?(Hash) && query.empty?)
+        # TODO: after adding Enumerable methods to Model, try to return self here
+        new_collection(self.query.dup)
+      else
+        new_collection(scoped_query(query))
+      end
     end
 
+    # Return the first Resource or the first N Resources for the Model with an optional query
+    #
+    # When there are no arguments, return the first Resource in the
+    # Model.  When the first argument is an Integer, return a
+    # Collection containing the first N Resources.  When the last
+    # (optional) argument is a Hash scope the results to the query.
+    #
+    # @param [Integer] limit (optional)
+    #   limit the returned Collection to a specific number of entries
+    # @param [Hash] query (optional)
+    #   scope the returned Resource or Collection to the supplied query
+    #
+    # @return [Resource, Collection]
+    #   The first resource in the entries of this collection,
+    #   or a new collection whose query has been merged
+    #
+    # @api public
     def first(*args)
-      query = args.last.respond_to?(:merge) ? args.pop : {}
-      query = scoped_query(query.merge(:limit => args.first || 1))
+      last_arg = args.last
+
+      limit      = args.first if args.first.kind_of?(Integer)
+      with_query = last_arg.respond_to?(:merge) && !last_arg.blank?
+
+      query = with_query ? last_arg : {}
 
-      if args.any?
-        query.repository.read_many(query)
+      query = if query.kind_of?(Query)
+        query.slice(0, limit || 1)
       else
-        query.repository.read_one(query)
+        offset = query.fetch(:offset, 0)
+        query  = query.except(:offset)
+        scoped_query(query).slice(offset, limit || 1)
+      end
+
+      if limit
+        all(query)
+      else
+        query.repository.read(query).first
       end
     end
 
-    def [](*key)
-      warn("#{name}[] is deprecated. Use #{name}.get! instead.")
-      get!(*key)
+    # Return the last Resource or the last N Resources for the Model with an optional query
+    #
+    # When there are no arguments, return the last Resource for the
+    # Model.  When the first argument is an Integer, return a
+    # Collection containing the last N Resources.  When the last
+    # (optional) argument is a Hash scope the results to the query.
+    #
+    # @param [Integer] limit (optional)
+    #   limit the returned Collection to a specific number of entries
+    # @param [Hash] query (optional)
+    #   scope the returned Resource or Collection to the supplied query
+    #
+    # @return [Resource, Collection]
+    #   The last resource in the entries of this collection,
+    #   or a new collection whose query has been merged
+    #
+    # @api public
+    def last(*args)
+      last_arg = args.last
+
+      limit      = args.first if args.first.kind_of?(Integer)
+      with_query = last_arg.respond_to?(:merge) && !last_arg.blank?
+
+      query = with_query ? last_arg : {}
+
+      query = if query.kind_of?(Query)
+        query.slice(0, limit || 1).reverse!
+      else
+        offset = query.fetch(:offset, 0)
+        query  = query.except(:offset)
+        scoped_query(query).slice(offset, limit || 1).reverse!
+      end
+
+      if limit
+        all(query)
+      else
+        query.repository.read(query).last
+      end
     end
 
-    def first_or_create(query, attributes = {})
-      first(query) || begin
-        resource = allocate
-        query = query.dup
+    # Finds the first Resource by conditions, or initializes a new
+    # Resource with the attributes if none found
+    #
+    # @param [Hash] conditions
+    #   The conditions to be used to search
+    # @param [Hash] attributes
+    #   The attributes to be used to create the record of none is found.
+    # @return [Resource]
+    #   The instance found by +query+, or created with +attributes+ if none found
+    #
+    # @api public
+    def first_or_new(conditions = {}, attributes = {})
+      first(conditions) || new(conditions.merge(attributes))
+    end
 
-        properties(repository_name).key.each do |property|
-          if value = query.delete(property.name)
-            resource.send("#{property.name}=", value)
-          end
-        end
+    # Finds the first Resource by conditions, or creates a new
+    # Resource with the attributes if none found
+    #
+    # @param [Hash] conditions
+    #   The conditions to be used to search
+    # @param [Hash] attributes
+    #   The attributes to be used to create the record of none is found.
+    # @return [Resource]
+    #   The instance found by +query+, or created with +attributes+ if none found
+    #
+    # @api public
+    def first_or_create(conditions = {}, attributes = {})
+      first(conditions) || create(conditions.merge(attributes))
+    end
 
-        resource.attributes = query.merge(attributes)
-        resource.save
-        resource
+    # Initializes an instance of Resource with the given attributes
+    #
+    # @param [Hash(Symbol => Object)] attributes
+    #   hash of attributes to set
+    #
+    # @return [Resource]
+    #   the newly initialized Resource instance
+    #
+    # @api public
+    chainable do
+      def new(*args, &block)
+        assert_valid
+        super
       end
     end
 
-    ##
-    # Create an instance of Resource with the given attributes
+    # Create a Resource
     #
-    # @param <Hash(Symbol => Object)> attributes hash of attributes to set
+    # @param [Hash(Symbol => Object)] attributes
+    #   attributes to set
+    #
+    # @return [Resource]
+    #   the newly created Resource instance
+    #
+    # @api public
     def create(attributes = {})
-      resource = new(attributes)
-      resource.save
-      resource
+      _create(true, attributes)
     end
 
-    ##
-    # This method is deprecated, and will be removed from dm-core.
+    # Create a Resource, bypassing hooks
+    #
+    # @param [Hash(Symbol => Object)] attributes
+    #   attributes to set
     #
+    # @return [Resource]
+    #   the newly created Resource instance
+    #
+    # @api public
     def create!(attributes = {})
-      warn("Model#create! is deprecated. It is moving to dm-validations, and will be used to create a record without validations")
-      resource = create(attributes)
-      raise PersistenceError, "Resource not saved: :new_record => #{resource.new_record?}, :dirty_attributes => #{resource.dirty_attributes.inspect}" if resource.new_record?
-      resource
+      _create(false, attributes)
     end
 
-    ##
     # Copy a set of records from one repository to another.
     #
     # @param [String] source
@@ -321,7 +426,7 @@ module DataMapper
     #   The conditions with which to find the records to copy. These
     #   conditions are merged with Model.query
     #
-    # @return [DataMapper::Collection]
+    # @return [Collection]
     #   A Collection of the Resource instances created in the operation
     #
     # @api public
@@ -329,198 +434,294 @@ module DataMapper
 
       # get the list of properties that exist in the source and destination
       destination_properties = properties(destination)
-      fields = query[:fields] ||= properties(source).select { |p| destination_properties.has_property?(p.name) }
+      fields = query[:fields] ||= properties(source).select { |property| destination_properties.include?(property) }
 
       repository(destination) do
-        all(query.merge(:repository => repository(source))).map do |resource|
-          create(fields.map { |p| [ p.name, p.get(resource) ] }.to_hash)
+        all(query.merge(:repository => source)).map do |resource|
+          create(fields.map { |property| [ property.name, property.get(resource) ] }.to_hash)
         end
       end
     end
 
-    # @api private
-    # TODO: spec this
-    def load(values, query)
-      repository = query.repository
-      model      = self
+    # Loads an instance of this Model, taking into account IdentityMap lookup,
+    # inheritance columns(s) and Property typecasting.
+    #
+    # @param [Enumerable(Object)] records
+    #   an Array of Resource or Hashes to load a Resource with
+    #
+    # @return [Resource]
+    #   the loaded Resource instance
+    #
+    # @api semipublic
+    def load(records, query)
+      repository      = query.repository
+      repository_name = repository.name
+      fields          = query.fields
+      discriminator   = properties(repository_name).discriminator
+      no_reload       = !query.reload?
 
-      if inheritance_property_index = query.inheritance_property_index
-        model = values.at(inheritance_property_index) || model
-      end
+      field_map = fields.map { |property| [ property, property.field ] }.to_hash
 
-      key_values = nil
-      identity_map = nil
+      records.map do |record|
+        identity_map = nil
+        key_values   = nil
+        resource     = nil
 
-      if key_property_indexes = query.key_property_indexes(repository)
-        key_values   = values.values_at(*key_property_indexes)
-        identity_map = repository.identity_map(model)
+        case record
+          when Hash
+            # remap fields to use the Property object
+            record = record.dup
+            field_map.each { |property, field| record[property] = record.delete(field) if record.key?(field) }
 
-        if resource = identity_map.get(key_values)
-          return resource unless query.reload?
-        else
-          resource = model.allocate
-          resource.instance_variable_set(:@repository, repository)
-        end
-      else
-        resource = model.allocate
-        resource.readonly!
-      end
+            model = discriminator && record[discriminator] || self
 
-      resource.instance_variable_set(:@new_record, false)
+            resource = if (key_values = record.values_at(*model.key(repository_name))).all?
+              identity_map = repository.identity_map(model)
+              identity_map[key_values]
+            end
 
-      query.fields.zip(values) do |property,value|
-        value = property.custom? ? property.type.load(value, property) : property.typecast(value)
-        property.set!(resource, value)
+            resource ||= model.allocate
 
-        if track = property.track
-          case track
-            when :hash
-              resource.original_values[property.name] = value.dup.hash unless resource.original_values.has_key?(property.name) rescue value.hash
-            when :load
-              resource.original_values[property.name] = value unless resource.original_values.has_key?(property.name)
-          end
+            fields.each do |property|
+              next if no_reload && property.loaded?(resource)
+
+              value = record[property]
+
+              # TODO: typecasting should happen inside the Adapter
+              # and all values should come back as expected objects
+              if property.custom?
+                value = property.type.load(value, property)
+              end
+
+              property.set!(resource, value)
+            end
+
+          when Resource
+            model = record.model
+
+            resource = if (key_values = record.key).all?
+              identity_map = repository.identity_map(model)
+              identity_map[key_values]
+            end
+
+            resource ||= model.allocate
+
+            fields.each do |property|
+              next if no_reload && property.loaded?(resource)
+
+              property.set!(resource, property.get!(record))
+            end
         end
-      end
 
-      if key_values && identity_map
-        identity_map.set(key_values, resource)
+        resource.instance_variable_set(:@repository, repository)
+        resource.instance_variable_set(:@saved,      true)
+
+        if identity_map
+          # defer setting the IdentityMap so second level caches can
+          # record the state of the resource after loaded
+          identity_map[key_values] = resource
+        else
+          resource.freeze
+        end
+
+        resource
       end
+    end
 
-      resource
+    # TODO: document
+    # @api semipublic
+    attr_reader :base_model
+
+    # TODO: document
+    # @api semipublic
+    def default_repository_name
+      Repository.default_name
     end
 
-    # TODO: spec this
-    def to_query(repository, key, query = {})
-      conditions = Hash[ *self.key(repository.name).zip(key).flatten ]
-      Query.new(repository, self, query.merge(conditions))
+    # TODO: document
+    # @api semipublic
+    def default_order(repository_name = default_repository_name)
+      @default_order[repository_name] ||= key(repository_name).map { |property| Query::Direction.new(property) }.freeze
     end
 
-    # TODO: add docs
+    # Get the repository with a given name, or the default one for the current
+    # context, or the default one for this class.
+    #
+    # @param [Symbol] name
+    #   the name of the repository wanted
+    # @param [Block] block
+    #   block to execute with the fetched repository as parameter
+    #
+    # @return [Object, Respository]
+    #   whatever the block returns, if given a block,
+    #   otherwise the requested repository.
+    #
     # @api private
-    def _load(marshalled)
-      resource = allocate
-      Marshal.load(marshalled).each { |kv| resource.instance_variable_set(*kv) }
-      resource
+    def repository(name = nil)
+      #
+      # There has been a couple of different strategies here, but me (zond) and dkubb are at least
+      # united in the concept of explicitness over implicitness. That is - the explicit wish of the
+      # caller (+name+) should be given more priority than the implicit wish of the caller (Repository.context.last).
+      #
+      if block_given?
+        DataMapper.repository(name || repository_name) { |*block_args| yield(*block_args) }
+      else
+        DataMapper.repository(name || repository_name)
+      end
     end
 
-    def typecast_key(key)
-      self.key(repository_name).zip(key).map { |k, v| k.typecast(v) }
+    # Get the current +repository_name+ for this Model.
+    #
+    # If there are any Repository contexts, the name of the last one will
+    # be returned, else the +default_repository_name+ of this model will be
+    #
+    # @return [String]
+    #   the current repository name to use for this Model
+    #
+    # @api private
+    def repository_name
+      Repository.context.any? ? Repository.context.last.name : default_repository_name
     end
 
-    def default_repository_name
-      Repository.default_name
+    # Gets the current Set of repositories for which
+    # this Model has been defined (beyond default)
+    #
+    # @return [Set]
+    #   The Set of repositories for which this Model
+    #   has been defined (beyond default)
+    #
+    # @api private
+    def repositories
+      [ repository ].to_set + @properties.keys.map { |repository_name| DataMapper.repository(repository_name) }
     end
 
-    def paranoid_properties
-      @paranoid_properties ||= {}
-      @paranoid_properties
+    # TODO: document
+    # @api private
+    def model_method_defined?(method)
+      model_methods.include?(method.to_s)
     end
 
-    private
-
-    def default_storage_name
-      self.name
+    # TODO: document
+    # @api private
+    def resource_method_defined?(method)
+      resource_methods.include?(method.to_s)
     end
 
-    def scoped_query(query = self.query)
-      assert_kind_of 'query', query, Query, Hash
+    private
 
-      return self.query if query == self.query
+    # TODO: document
+    # @api private
+    def _create(safe, attributes)
+      resource = new(attributes)
+      resource.send(safe ? :save : :save!)
+      resource
+    end
 
-      query = if query.kind_of?(Hash)
-        Query.new(query.has_key?(:repository) ? query.delete(:repository) : self.repository, self, query)
+    # TODO: document
+    # @api private
+    def const_missing(name)
+      if name == :DM
+        warn "#{name} prefix deprecated and no longer necessary (#{caller[0]})"
+        self
+      elsif name == :Resource
+        Resource
+      elsif Types.const_defined?(name)
+        Types.const_get(name)
       else
-        query
+        super
       end
+    end
 
-      if self.query
-        self.query.merge(query)
-      else
-        merge_with_default_scope(query)
-      end
+    # TODO: document
+    # @api private
+    def default_storage_name
+      base_model.name
     end
 
-    def set_paranoid_property(name, &block)
-      self.paranoid_properties[name] = block
+    # Initializes a new Collection
+    #
+    # @return [Collection]
+    #   A new Collection object
+    #
+    # @api private
+    def new_collection(query, resources = nil, &block)
+      Collection.new(query, resources, &block)
     end
 
-    # defines the getter for the property
-    def create_property_getter(property)
-      class_eval <<-EOS, __FILE__, __LINE__
-        #{property.reader_visibility}
-        def #{property.getter}
-          attribute_get(#{property.name.inspect})
+    # @api private
+    # TODO: move the logic to create relative query into Query
+    def scoped_query(query)
+      if query.kind_of?(Query)
+        query.dup
+      else
+        repository = if query.key?(:repository)
+          query      = query.dup
+          repository = query.delete(:repository)
+
+          if repository.kind_of?(Symbol)
+            DataMapper.repository(repository)
+          else
+            repository
+          end
+        else
+          self.repository
         end
-      EOS
 
-      if property.primitive == TrueClass && !instance_methods.map { |m| m.to_s }.include?(property.name.to_s)
-        class_eval <<-EOS, __FILE__, __LINE__
-          #{property.reader_visibility}
-          alias #{property.name} #{property.getter}
-        EOS
+        if self.query.repository == repository
+          self.query.merge(query)
+        else
+          Query.new(repository, self, self.query.merge(query).options)
+        end
       end
     end
 
-    # defines the setter for the property
-    def create_property_setter(property)
-      unless instance_methods.map { |m| m.to_s }.include?("#{property.name}=")
-        class_eval <<-EOS, __FILE__, __LINE__
-          #{property.writer_visibility}
-          def #{property.name}=(value)
-            attribute_set(#{property.name.inspect}, value)
-          end
-        EOS
-      end
-    end
+    # @api private
+    def assert_valid # :nodoc:
+      return if @valid
+      @valid = true
 
-    def relationships(*args)
-      # DO NOT REMOVE!
-      # method_missing depends on these existing. Without this stub,
-      # a missing module can cause misleading recursive errors.
-      raise NotImplementedError.new
-    end
+      if properties(repository_name).empty? &&
+        !relationships(repository_name).any? { |(relationship_name, relationship)| relationship.kind_of?(Associations::ManyToOne::Relationship) }
+        raise IncompleteModelError, "#{name} must have at least one property or many to one relationship to be valid"
+      end
 
-    def method_missing(method, *args, &block)
-      if relationship = self.relationships(repository_name)[method]
-        klass = self == relationship.child_model ? relationship.parent_model : relationship.child_model
-        return DataMapper::Query::Path.new(repository, [ relationship ], klass)
+      if key(repository_name).empty?
+        raise IncompleteModelError, "#{name} must have a key to be valid"
       end
 
-      property_set = properties(repository_name)
-      if property_set.has_property?(method)
-        return property_set[method]
+      # initialize join models and target keys
+      @relationships.each_value do |relationships|
+        relationships.each_value do |relationship|
+          relationship.child_key
+          relationship.through if relationship.respond_to?(:through)
+          relationship.via     if relationship.respond_to?(:via)
+        end
       end
+    end
 
-      super
+    # TODO: document
+    # @api private
+    def model_methods
+      @model_methods ||= ancestor_instance_methods { |mod| mod.meta_class }
     end
 
-    # TODO: move to dm-more/dm-transactions
-    module Transaction
-      #
-      # Produce a new Transaction for this Resource class
-      #
-      # @return <DataMapper::Adapters::Transaction
-      #   a new DataMapper::Adapters::Transaction with all DataMapper::Repositories
-      #   of the class of this DataMapper::Resource added.
-      #-
-      # @api public
-      #
-      # TODO: move to dm-more/dm-transactions
-      def transaction
-        DataMapper::Transaction.new(self) { |block_args| yield(*block_args) }
-      end
-    end # module Transaction
+    # TODO: document
+    # @api private
+    def resource_methods
+      @resource_methods ||= ancestor_instance_methods { |mod| mod }
+    end
 
-    include Transaction
+    # TODO: document
+    # @api private
+    def ancestor_instance_methods
+      methods = Set.new
 
-    # TODO: move to dm-more/dm-migrations
-    module Migration
-      # TODO: move to dm-more/dm-migrations
-      def storage_exists?(repository_name = default_repository_name)
-        repository(repository_name).storage_exists?(storage_name(repository_name))
+      ancestors.each do |mod|
+        next unless mod <= DataMapper::Resource
+        methods.merge(yield(mod).instance_methods(false).map { |method| method.to_s })
       end
-    end # module Migration
 
-    include Migration
+      methods
+    end
   end # module Model
 end # module DataMapper