dm-core 0.9.11 → 0.10.0

data/lib/dm-core/query/sort.rb

@@ -0,0 +1,45 @@
+# TODO: add #reverse and #reverse! methods
+
+module DataMapper
+  class Query
+    class Sort
+      # TODO: document
+      # @api semipublic
+      attr_reader :value
+
+      # TODO: document
+      # @api semipublic
+      def direction
+        @ascending ? :ascending : :descending
+      end
+
+      # TODO: document
+      # @api private
+      def <=>(other)
+        other_value = other.value
+
+        cmp = case
+          when @value.nil? && other_value.nil?
+            0
+          when @value.nil?
+            1
+          when other_value.nil?
+            -1
+          else
+            @value <=> other_value
+        end
+
+        @ascending ? cmp : cmp * -1
+      end
+
+      private
+
+      # TODO: document
+      # @api private
+      def initialize(value, ascending = true)
+        @value     = value
+        @ascending = ascending
+      end
+    end # class Sort
+  end # class Query
+end # module DataMapper

data/lib/dm-core/repository.rb

@@ -1,106 +1,264 @@
 module DataMapper
   class Repository
-    include Assertions
+    include Extlib::Assertions
 
-    @adapters = {}
-
-    ##
+    # Get the list of adapters registered for all Repositories,
+    # keyed by repository name.
+    #
+    #   TODO: create example
+    #
+    # @return [Hash(Symbol => Adapters::AbstractAdapter)]
+    #   the adapters registered for all Repositories
     #
-    # @return <Adapter> the adapters registered for this repository
+    # @api private
     def self.adapters
-      @adapters
+      @adapters ||= {}
     end
 
+    # Get the stack of current repository contexts
+    #
+    #   TODO: create example
+    #
+    # @return [Array]
+    #   List of Repository contexts for the current Thread
+    #
+    # @api private
     def self.context
       Thread.current[:dm_repository_contexts] ||= []
     end
 
+    # Get the default name of this Repository
+    #
+    #   TODO: create example
+    #
+    # @return [Symbol]
+    #   the default name of this repository
+    #
+    # @api private
     def self.default_name
       :default
     end
 
+    # TODO: document
+    # @api semipublic
     attr_reader :name
 
+    # Get the adapter for this repository
+    #
+    # Lazy loads adapter setup from registered adapters
+    #
+    #   TODO: create example
+    #
+    # @return [Adapters::AbstractAdapter]
+    #   the adapter for this repository
+    #
+    # @raise [RepositoryNotSetupError]
+    #   if there is no adapter registered for a repository named @name
+    #
+    # @api semipublic
     def adapter
       # Make adapter instantiation lazy so we can defer repository setup until it's actually
       # needed. Do not remove this code.
-      @adapter ||= begin
-        raise ArgumentError, "Adapter not set: #{@name}. Did you forget to setup?" \
-          unless self.class.adapters.has_key?(@name)
+      @adapter ||=
+        begin
+          raise RepositoryNotSetupError, "Adapter not set: #{@name}. Did you forget to setup?" \
+            unless self.class.adapters.key?(@name)
 
-        self.class.adapters[@name]
-      end
+          self.class.adapters[@name]
+        end
     end
 
+    # Get the identity for a particular model within this repository.
+    #
+    # If one doesn't yet exist, create a new default in-memory IdentityMap
+    # for the requested model.
+    #
+    #   TODO: create example
+    #
+    # @param [Model] model
+    #   Model whose identity map should be returned
+    #
+    # @return [IdentityMap]
+    #   The IdentityMap for model in this Repository
+    #
+    # @api private
     def identity_map(model)
-      @identity_maps[model] ||= IdentityMap.new
+      @identity_maps[model.base_model] ||= IdentityMap.new
     end
 
-    # TODO: spec this
+    # Executes a block in the scope of this Repository
+    #
+    #   TODO: create example
+    #
+    # @yieldparam [Repository] repository
+    #   yields self within the block
+    #
+    # @yield
+    #   execute block in the scope of this Repository
+    #
+    # @api private
     def scope
       Repository.context << self
 
       begin
-        return yield(self)
+        yield self
       ensure
         Repository.context.pop
       end
     end
 
+    # Create one or more resource instances in this repository.
+    #
+    #   TODO: create example
+    #
+    # @param [Enumerable(Resource)] resources
+    #   The list of resources (model instances) to create
+    #
+    # @return [Integer]
+    #   The number of records that were actually saved into the data-store
+    #
+    # @api semipublic
     def create(resources)
       adapter.create(resources)
     end
 
-    ##
-    # retrieve a collection of results of a query
+    # Retrieve a collection of results of a query
     #
-    # @param <Query> query composition of the query to perform
-    # @return <DataMapper::Collection> result set of the query
-    # @see DataMapper::Query
-    def read_many(query)
-      adapter.read_many(query)
-    end
-
-    ##
-    # retrieve a resource instance by a query
+    #   TODO: create example
     #
-    # @param <Query> query composition of the query to perform
-    # @return <DataMapper::Resource> the first retrieved instance which matches the query
-    # @return <NilClass> no object could be found which matches that query
-    # @see DataMapper::Query
-    def read_one(query)
-      adapter.read_one(query)
+    # @param [Query] query
+    #   composition of the query to perform
+    #
+    # @return [Array]
+    #   result set of the query
+    #
+    # @api semipublic
+    def read(query)
+      return [] unless query.valid?
+      query.model.load(adapter.read(query), query)
     end
 
-    def update(attributes, query)
-      adapter.update(attributes, query)
+    # Update the attributes of one or more resource instances
+    #
+    #   TODO: create example
+    #
+    # @param [Hash(Property => Object)] attributes
+    #   hash of attribute values to set, keyed by Property
+    # @param [Collection] collection
+    #   collection of records to be updated
+    #
+    # @return [Integer]
+    #   the number of records updated
+    #
+    # @api semipublic
+    def update(attributes, collection)
+      return 0 unless collection.query.valid?
+      adapter.update(attributes, collection)
     end
 
-    def delete(query)
-      adapter.delete(query)
+    # Delete one or more resource instances
+    #
+    #   TODO: create example
+    #
+    # @param [Collection] collection
+    #   collection of records to be deleted
+    #
+    # @return [Integer]
+    #   the number of records deleted
+    #
+    # @api semipublic
+    def delete(collection)
+      return 0 unless collection.query.valid?
+      adapter.delete(collection)
     end
 
+    # Compares another Repository for equality
+    #
+    # Repository is equal to +other+ if they are the same object (identity)
+    # or if they are of the same class and have the same name
+    #
+    # @param [Repository] other
+    #   the other Repository to compare with
+    #
+    # @return [Boolean]
+    #   true if they are equal, false if not
+    #
+    # @api public
     def eql?(other)
-      return true if super
-      name == other.name
+      if equal?(other)
+        return true
+      end
+
+      unless instance_of?(other.class)
+        return false
+      end
+
+      cmp?(other, :eql?)
     end
 
-    alias == eql?
+    # Compares another Repository for equivalency
+    #
+    # Repository is equal to +other+ if they are the same object (identity)
+    # or if they both have the same name
+    #
+    # @param [Repository] other
+    #   the other Repository to compare with
+    #
+    # @return [Boolean]
+    #   true if they are equal, false if not
+    #
+    # @api public
+    def ==(other)
+      if equal?(other)
+        return true
+      end
 
-    def to_s
-      "#<DataMapper::Repository:#{@name}>"
+      unless other.respond_to?(:name)
+        return false
+      end
+
+      unless other.respond_to?(:adapter)
+        return false
+      end
+
+      cmp?(other, :==)
     end
 
-    def _dump(*)
-      name.to_s
+    # Return the hash of the Repository
+    #
+    # This is necessary for properly determining the unique Repository
+    # in a Set or Hash
+    #
+    # @return [Integer]
+    #   the Hash of the Repository name
+    #
+    # @api private
+    def hash
+      name.hash
     end
 
-    def self._load(marshalled)
-      new(marshalled.to_sym)
+    # Return a human readable representation of the repository
+    #
+    #   TODO: create example
+    #
+    # @return [String]
+    #   human readable representation of the repository
+    #
+    # @api private
+    def inspect
+      "#<#{self.class.name} @name=#{@name}>"
     end
 
     private
 
+    # Initializes a new Repository
+    #
+    #   TODO: create example
+    #
+    # @param [Symbol] name
+    #   The name of the Repository
+    #
+    # @api semipublic
     def initialize(name)
       assert_kind_of 'name', name, Symbol
 
@@ -108,60 +266,18 @@ module DataMapper
       @identity_maps = {}
     end
 
-    # TODO: move to dm-more/dm-migrations
-    module Migration
-      # TODO: move to dm-more/dm-migrations
-      def map(*args)
-        type_map.map(*args)
-      end
-
-      # TODO: move to dm-more/dm-migrations
-      def type_map
-        @type_map ||= TypeMap.new(adapter.class.type_map)
+    # TODO: document
+    # @api private
+    def cmp?(other, operator)
+      unless name.send(operator, other.name)
+        return false
       end
 
-      ##
-      #
-      # @return <True, False> whether or not the data-store exists for this repo
-      #
-      # TODO: move to dm-more/dm-migrations
-      def storage_exists?(storage_name)
-        adapter.storage_exists?(storage_name)
+      unless adapter.send(operator, other.adapter)
+        return false
       end
 
-      # TODO: move to dm-more/dm-migrations
-      def migrate!
-        Migrator.migrate(name)
-      end
-
-      # TODO: move to dm-more/dm-migrations
-      def auto_migrate!
-        AutoMigrator.auto_migrate(name)
-      end
-
-      # TODO: move to dm-more/dm-migrations
-      def auto_upgrade!
-        AutoMigrator.auto_upgrade(name)
-      end
+      true
     end
-
-    include Migration
-
-    # TODO: move to dm-more/dm-transactions
-    module Transaction
-      ##
-      # Produce a new Transaction for this Repository
-      #
-      #
-      # @return <DataMapper::Adapters::Transaction> a new Transaction (in state
-      #   :none) that can be used to execute code #with_transaction
-      #
-      # TODO: move to dm-more/dm-transactions
-      def transaction
-        DataMapper::Transaction.new(self)
-      end
-    end
-
-    include Transaction
   end # class Repository
 end # module DataMapper

data/lib/dm-core/resource.rb

@@ -1,94 +1,161 @@
-require 'set'
-
 module DataMapper
   module Resource
-    include Assertions
+    include Extlib::Assertions
+    extend Chainable
+    extend Deprecate
 
-    ##
-    #
-    # Appends a module for inclusion into the model class after
-    # DataMapper::Resource.
-    #
-    # This is a useful way to extend DataMapper::Resource while still retaining
-    # a self.included method.
-    #
-    # @param [Module] inclusion the module that is to be appended to the module
-    #   after DataMapper::Resource
-    #
-    # @return [TrueClass, FalseClass] whether or not the inclusions have been
-    #   successfully appended to the list
-    # @return <TrueClass, FalseClass>
-    #-
-    # @api public
+    deprecate :new_record?, :new?
+
+    # @deprecated
     def self.append_inclusions(*inclusions)
-      extra_inclusions.concat inclusions
-      true
+      warn "DataMapper::Resource.append_inclusions is deprecated, use DataMapper::Model.append_inclusions instead (#{caller[0]})"
+      Model.append_inclusions(*inclusions)
     end
 
+    # @deprecated
     def self.extra_inclusions
-      @extra_inclusions ||= []
+      warn "DataMapper::Resource.extra_inclusions is deprecated, use DataMapper::Model.extra_inclusions instead (#{caller[0]})"
+      Model.extra_inclusions
+    end
+
+    # @deprecated
+    def self.descendants
+      warn "DataMapper::Resource.descendants is deprecated, use DataMapper::Model.descendants instead (#{caller[0]})"
+      DataMapper::Model.descendants
+    end
+
+    # Deprecated API for updating attributes and saving Resource
+    #
+    # @see #update
+    #
+    # @deprecated
+    def update_attributes(attributes = {}, *allowed)
+      assert_update_clean_only(:update_attributes)
+
+      warn "#{model}#update_attributes is deprecated, use #{model}#update instead (#{caller[0]})"
+
+      if allowed.any?
+        warn "specifying allowed in #{model}#update_attributes is deprecated, " \
+          "use Hash#only to filter the attributes in the caller (#{caller[0]})"
+        attributes = attributes.only(*allowed)
+      end
+
+      update(attributes)
     end
 
-    # When Resource is included in a class this method makes sure
-    # it gets all the methods
+    # Makes sure a class gets all the methods when it includes Resource
     #
-    # -
     # @api private
     def self.included(model)
       model.extend Model
-      model.extend ClassMethods if defined?(ClassMethods)
-      model.const_set('Resource', self) unless model.const_defined?('Resource')
-      extra_inclusions.each { |inclusion| model.send(:include, inclusion) }
-      descendants << model
-      class << model
-        @_valid_model = false
-        attr_reader :_valid_model
-      end
     end
 
-    # Return all classes that include the DataMapper::Resource module
+    # Collection this resource associated with.
+    # Used by SEL.
     #
-    # ==== Returns
-    # Set:: a set containing the including classes
+    # @api private
+    attr_writer :collection
+
+    # TODO: document
+    # @api public
+    alias_method :model, :class
+
+    # Repository this resource belongs to in the context of this collection
+    # or of the resource's class.
     #
-    # ==== Example
+    # @return [Repository]
+    #   the respository this resource belongs to, in the context of
+    #   a collection OR in the instance's Model's context
     #
-    #   Class Foo
-    #     include DataMapper::Resource
-    #   end
+    # @api semipublic
+    def repository
+      # only set @repository explicitly when persisted
+      defined?(@repository) ? @repository : model.repository
+    end
+
+    # Retrieve the key(s) for this resource.
     #
-    #   DataMapper::Resource.descendants.to_a.first == Foo
+    # This always returns the persisted key value,
+    # even if the key is changed and not yet persisted.
+    # This is done so all relations still work.
     #
-    # -
-    # @api semipublic
-    def self.descendants
-      @descendants ||= Set.new
+    # @return [Array(Key)]
+    #   the key(s) identifying this resource
+    #
+    # @api public
+    def key
+      return @key if defined?(@key)
+
+      key = model.key(repository_name).map do |property|
+        original_attributes[property] || (property.loaded?(self) ? property.get!(self) : nil)
+      end
+
+      return unless key.all?
+
+      # memoize the key if the Resource is not frozen
+      @key = key unless frozen?
+
+      key
     end
 
-    # +---------------
-    # Instance methods
+    # Checks if this Resource instance is new
+    #
+    # @return [Boolean]
+    #   true if the resource is new and not saved
+    #
+    # @api public
+    def new?
+      !saved?
+    end
 
-    attr_writer :collection
+    # Checks if this Resource instance is saved
+    #
+    # @return [Boolean]
+    #   true if the resource has been saved
+    #
+    # @api public
+    def saved?
+      @saved == true
+    end
 
-    alias model class
+    # Checks if the resource has no changes to save
+    #
+    # @return [Boolean]
+    #   true if the resource may not be persisted
+    #
+    # @api public
+    def clean?
+      !dirty?
+    end
 
-    # returns the value of the attribute. Do not read from instance variables directly,
-    # but use this method. This method handels the lazy loading the attribute and returning
-    # of defaults if nessesary.
+    # Checks if the resource has unsaved changes
     #
-    # ==== Parameters
-    # name<Symbol>:: name attribute to lookup
+    # @return [Boolean]
+    #  true if resource may be persisted
     #
-    # ==== Returns
-    # <Types>:: the value stored at that given attribute, nil if none, and default if necessary
+    # @api public
+    def dirty?
+      if original_attributes.any?
+        true
+      elsif new?
+        model.serial || properties.any? { |property| property.default? }
+      else
+        false
+      end
+    end
+
+    # Returns the value of the attribute.
     #
-    # ==== Example
+    # Do not read from instance variables directly, but use this method.
+    # This method handles lazy loading the attribute and returning of
+    # defaults if nessesary.
     #
-    #   Class Foo
+    # @example
+    #   class Foo
     #     include DataMapper::Resource
     #
     #     property :first_name, String
-    #     property :last_name, String
+    #     property :last_name,  String
     #
     #     def full_name
     #       "#{attribute_get(:first_name)} #{attribute_get(:last_name)}"
@@ -100,32 +167,32 @@ module DataMapper
     #     end
     #   end
     #
-    # -
-    # @api semipublic
+    # @param [Symbol] name
+    #   name of attribute to retrieve
+    #
+    # @return [Object]
+    #   the value stored at that given attribute
+    #   (nil if none, and default if necessary)
+    #
+    # @api public
     def attribute_get(name)
       properties[name].get(self)
     end
 
-    # sets the value of the attribute and marks the attribute as dirty
+    alias [] attribute_get
+
+    # Sets the value of the attribute and marks the attribute as dirty
     # if it has been changed so that it may be saved. Do not set from
     # instance variables directly, but use this method. This method
-    # handels the lazy loading the property and returning of defaults
+    # handles the lazy loading the property and returning of defaults
     # if nessesary.
     #
-    # ==== Parameters
-    # name<Symbol>:: name attribute to set
-    # value<Type>:: value to store at that location
-    #
-    # ==== Returns
-    # <Types>:: the value stored at that given attribute, nil if none, and default if necessary
-    #
-    # ==== Example
-    #
-    #   Class Foo
+    # @example
+    #   class Foo
     #     include DataMapper::Resource
     #
     #     property :first_name, String
-    #     property :last_name, String
+    #     property :last_name,  String
     #
     #     def full_name(name)
     #       name = name.split(' ')
@@ -141,531 +208,684 @@ module DataMapper
     #     end
     #   end
     #
-    # -
-    # @api semipublic
+    # @param [Symbol] name
+    #   name of attribute to set
+    # @param [Object] value
+    #   value to store
+    #
+    # @return [Object]
+    #   the value stored at that given attribute, nil if none,
+    #   and default if necessary
+    #
+    # @api public
     def attribute_set(name, value)
       properties[name].set(self, value)
     end
 
-    # Compares if its the same object or if attributes are equal
+    alias []= attribute_set
+
+    # Gets all the attributes of the Resource instance
     #
-    # The comparaison is
-    #  * false if object not from same repository
-    #  * false if object has no all same properties
+    # @param [Symbol] key_on
+    #   Use this attribute of the Property as keys.
+    #   defaults to :name. :field is useful for adapters
+    #   :property or nil use the actual Property object.
     #
+    # @return [Hash]
+    #   All the attributes
+    #
+    # @api public
+    def attributes(key_on = :name)
+      attributes = {}
+      properties.each do |property|
+        if model.public_method_defined?(name = property.name)
+          key = case key_on
+            when :name  then name
+            when :field then property.field
+            else             property
+          end
+
+          attributes[key] = send(name)
+        end
+      end
+      attributes
+    end
+
+    # Assign values to multiple attributes in one call (mass assignment)
     #
-    # ==== Parameters
-    # other<Object>:: Object to compare to
+    # @param [Hash] attributes
+    #   names and values of attributes to assign
     #
-    # ==== Returns
-    # <True>:: the outcome of the comparison as a boolean
+    # @return [Hash]
+    #   names and values of attributes assigned
     #
-    # -
     # @api public
-    def eql?(other)
-      return true if equal?(other)
-
-      # two instances for different models cannot be equivalent
-      return false unless other.kind_of?(model)
-
-      # two instances with different keys cannot be equivalent
-      return false if key != other.key
-
-      # neither object has changed since loaded, so they are equivalent
-      return true if repository == other.repository && !dirty? && !other.dirty?
-
-      # get all the loaded and non-loaded properties that are not keys,
-      # since the key comparison was performed earlier
-      loaded, not_loaded = properties.select { |p| !p.key? }.partition do |property|
-        attribute_loaded?(property.name) && other.attribute_loaded?(property.name)
+    def attributes=(attributes)
+      attributes.each do |name, value|
+        case name
+          when String, Symbol
+            if model.public_method_defined?(setter = "#{name}=")
+              send(setter, value)
+            else
+              raise ArgumentError, "The attribute '#{name}' is not accessible in #{model}"
+            end
+          when Associations::Relationship, Property
+            name.set(self, value)
+        end
       end
-
-      # check all loaded properties, and then all unloaded properties
-      (loaded + not_loaded).all? { |p| p.get(self) == p.get(other) }
     end
 
-    alias == eql?
-
-    # Computes a hash for the resource
+    # Reloads association and all child association
     #
-    # ==== Returns
-    # <Integer>:: the hash value of the resource
+    # @return [Resource]
+    #   the receiver, the current Resource instance
     #
-    # -
     # @api public
-    def hash
-      model.hash + key.hash
+    def reload
+      if saved?
+        reload_attributes(loaded_properties)
+        child_relationships.each { |relationship| relationship.get!(self).reload }
+      end
+
+      self
     end
 
-    # Inspection of the class name and the attributes
+    # Updates attributes and saves this Resource instance
     #
-    # ==== Returns
-    # <String>:: with the class name, attributes with their values
+    # @param [Hash] attributes
+    #   attributes to be updated
     #
-    # ==== Example
+    # @return [Boolean]
+    #   true if resource and storage state match
     #
-    # >> Foo.new
-    # => #<Foo name=nil updated_at=nil created_at=nil id=nil>
-    #
-    # -
     # @api public
-    def inspect
-      attrs = []
-
-      properties.each do |property|
-        value = if !attribute_loaded?(property.name) && !new_record?
-          '<not loaded>'
-        else
-          send(property.getter).inspect
-        end
-
-        attrs << "#{property.name}=#{value}"
+    chainable do
+      def update(attributes = {})
+        assert_update_clean_only(:update)
+        self.attributes = attributes
+        save
       end
+    end
 
-      "#<#{model.name} #{attrs * ' '}>"
+    # Updates attributes and saves this Resource instance, bypassing hooks
+    #
+    # @param [Hash] attributes
+    #   attributes to be updated
+    #
+    # @return [Boolean]
+    #   true if resource and storage state match
+    #
+    # @api public
+    def update!(attributes = {})
+      assert_update_clean_only(:update!)
+      self.attributes = attributes
+      save!
     end
 
-    # TODO docs
-    def pretty_print(pp)
-      pp.group(1, "#<#{model.name}", ">") do
-        pp.breakable
-        pp.seplist(attributes.to_a) do |k_v|
-          pp.text k_v[0].to_s
-          pp.text " = "
-          pp.pp k_v[1]
-        end
+    # Save the instance and loaded, dirty associations to the data-store
+    #
+    # @return [Boolean]
+    #   true if Resource instance and all associations were saved
+    #
+    # @api public
+    chainable do
+      def save
+        save_parents && save_self && save_children
       end
     end
 
-    ##
+    # Save the instance and loaded, dirty associations to the data-store, bypassing hooks
     #
-    # ==== Returns
-    # <Repository>:: the respository this resource belongs to in the context of a collection OR in the class's context
+    # @return [Boolean]
+    #   true if Resource instance and all associations were saved
     #
     # @api public
-    def repository
-      @repository || model.repository
+    def save!
+      save_parents(false) && save_self(false) && save_children(false)
     end
 
-    # default id method to return the resource id when there is a
-    # single key, and the model was defined with a primary key named
-    # something other than id
+    # Destroy the instance, remove it from the repository
     #
-    # ==== Returns
-    # <Array[Key], Key> key or keys
+    # @return [Boolean]
+    #   true if resource was destroyed
     #
-    # --
     # @api public
-    def id
-      key = self.key
-      key.first if key.size == 1
+    chainable do
+      def destroy
+        destroy!
+      end
     end
 
-    def key
-      key_properties.map do |property|
-        original_values[property.name] || property.get!(self)
+    # Destroy the instance, remove it from the repository, bypassing hooks
+    #
+    # @return [Boolean]
+    #   true if resource was destroyed
+    #
+    # @api public
+    def destroy!
+      if saved? && repository.delete(Collection.new(query, [ self ])) == 1
+        @collection.delete(self) if @collection
+        reset
+        freeze
+        true
+      else
+        false
       end
     end
 
-    def readonly!
-      @readonly = true
-    end
+    # Compares another Resource for equality
+    #
+    # Resource is equal to +other+ if they are the same object (identity)
+    # or if they are both of the *same model* and all of their attributes
+    # are equivalent
+    #
+    # @param [Resource] other
+    #   the other Resource to compare with
+    #
+    # @return [Boolean]
+    #   true if they are equal, false if not
+    #
+    # @api public
+    def eql?(other)
+      return true if equal?(other)
+      return false unless instance_of?(other.class)
 
-    def readonly?
-      @readonly == true
+      cmp?(other, :eql?)
     end
 
-    # save the instance to the data-store
+    # Compares another Resource for equivalency
     #
-    # ==== Returns
-    # <True, False>:: results of the save
+    # Resource is equal to +other+ if they are the same object (identity)
+    # or if they are both of the *same base model* and all of their attributes
+    # are equivalent
     #
-    # @see DataMapper::Repository#save
+    # @param [Resource] other
+    #   the other Resource to compare with
     #
-    # --
-    # #public
-    def save(context = :default)
-      # Takes a context, but does nothing with it. This is to maintain the
-      # same API through out all of dm-more. dm-validations requires a
-      # context to be passed
-
-      associations_saved = false
-      child_associations.each { |a| associations_saved |= a.save }
+    # @return [Boolean]
+    #   true if they are equivalent, false if not
+    #
+    # @api public
+    def ==(other)
+      return true if equal?(other)
+      return false unless other.respond_to?(:model) && model.base_model.equal?(other.model.base_model)
 
-      saved = new_record? ? create : update
+      cmp?(other, :==)
+    end
 
-      if saved
-        original_values.clear
+    # Compares two Resources to allow them to be sorted
+    #
+    # @param [Resource] other
+    #   The other Resource to compare with
+    #
+    # @return [Integer]
+    #   Return 0 if Resources should be sorted as the same, -1 if the
+    #   other Resource should be after self, and 1 if the other Resource
+    #   should be before self
+    #
+    # @api public
+    def <=>(other)
+      unless other.kind_of?(model.base_model)
+        raise ArgumentError, "Cannot compare a #{other.model} instance with a #{model} instance"
       end
+      cmp = 0
+      model.default_order(repository_name).map do |direction|
+        cmp = direction.get(self) <=> direction.get(other)
+        break if cmp != 0
+      end
+      cmp
+    end
 
-      parent_associations.each { |a| associations_saved |= a.save }
-
-      # We should return true if the model (or any of its associations)
-      # were saved.
-      (saved | associations_saved) == true
+    # Returns hash value of the object.
+    # Two objects with the same hash value assumed equal (using eql? method)
+    #
+    # DataMapper resources are equal when their models have the same hash
+    # and they have the same set of properties
+    #
+    # When used as key in a Hash or Hash subclass, objects are compared
+    # by eql? and thus hash value has direct effect on lookup
+    #
+    # @api private
+    def hash
+      key.hash
     end
 
-    # destroy the instance, remove it from the repository
+    # Get a Human-readable representation of this Resource instance
+    #
+    #   Foo.new   #=> #<Foo name=nil updated_at=nil created_at=nil id=nil>
     #
-    # ==== Returns
-    # <True, False>:: results of the destruction
+    # @return [String]
+    #   Human-readable representation of this Resource instance
     #
-    # --
     # @api public
-    def destroy
-      return false if new_record?
-      return false unless repository.delete(to_query)
-
-      @new_record = true
-      repository.identity_map(model).delete(key)
-      original_values.clear
+    def inspect
+      # TODO: display relationship values
+      attrs = properties.map do |property|
+        value = if new? || property.loaded?(self)
+          property.get!(self).inspect
+        else
+          '<not loaded>'
+        end
 
-      properties.each do |property|
-        # We'll set the original value to nil as if we had a new record
-        original_values[property.name] = nil if attribute_loaded?(property.name)
+        "#{property.instance_variable_name}=#{value}"
       end
 
-      true
+      "#<#{model.name} #{attrs.join(' ')}>"
     end
 
-    # Checks if the attribute has been loaded
+    # Hash of original values of attributes that have unsaved changes
     #
-    # ==== Example
+    # @return [Hash]
+    #   original values of attributes that have unsaved changes
+    #
+    # @api semipublic
+    def original_attributes
+      @original_attributes ||= {}
+    end
+
+    # Checks if an attribute has been loaded from the repository
     #
+    # @example
     #   class Foo
     #     include DataMapper::Resource
-    #     property :name, String
-    #     property :description, Text, :lazy => false
+    #
+    #     property :name,        String
+    #     property :description, Text,   :lazy => false
     #   end
     #
-    #   Foo.new.attribute_loaded?(:description) # will return false
+    #   Foo.new.attribute_loaded?(:description)   #=> false
     #
-    # --
-    # @api public
+    # @return [Boolean]
+    #   true if ivar +name+ has been loaded
+    #
+    # @return [Boolean]
+    #   true if ivar +name+ has been loaded
+    #
+    # @api private
     def attribute_loaded?(name)
-      instance_variable_defined?(properties[name].instance_variable_name)
+      properties[name].loaded?(self)
     end
 
-    # fetches all the names of the attributes that have been loaded,
+    # Fetches all the names of the attributes that have been loaded,
     # even if they are lazy but have been called
     #
-    # ==== Returns
-    # Array[<Symbol>]:: names of attributes that have been loaded
-    #
-    # ==== Example
-    #
+    # @example
     #   class Foo
     #     include DataMapper::Resource
-    #     property :name, String
-    #     property :description, Text, :lazy => false
+    #
+    #     property :name,        String
+    #     property :description, Text,   :lazy => false
     #   end
     #
-    #   Foo.new.loaded_attributes # returns [:name]
+    #   Foo.new.loaded_properties   #=>  [ #<Property @model=Foo @name=:name> ]
     #
-    # --
-    # @api public
-    def loaded_attributes
-      properties.map{|p| p.name if attribute_loaded?(p.name)}.compact
+    # @return [Array(Property)]
+    #   names of attributes that have been loaded
+    #
+    # @api private
+    def loaded_properties
+      properties.select { |property| property.loaded?(self) }
     end
 
-    # set of original values of properties
+    # Checks if an attribute has unsaved changes
     #
-    # ==== Returns
-    # Hash:: original values of properties
+    # @param [Symbol] name
+    #   name of attribute to check for unsaved changes
     #
-    # --
-    # @api public
-    def original_values
-      @original_values ||= {}
+    # @return [Boolean]
+    #   true if attribute has unsaved changes
+    #
+    # @api semipublic
+    def attribute_dirty?(name)
+      dirty_attributes.key?(properties[name])
     end
 
-    # Hash of attributes that have been marked dirty
+    # Hash of attributes that have unsaved changes
     #
-    # ==== Returns
-    # Hash:: attributes that have been marked dirty
+    # @return [Hash]
+    #   attributes that have unsaved changes
     #
-    # --
-    # @api private
+    # @api semipublic
     def dirty_attributes
       dirty_attributes = {}
-      properties       = self.properties
 
-      original_values.each do |name, old_value|
-        property  = properties[name]
-        new_value = property.get!(self)
-
-        dirty = case property.track
-        when :hash then old_value != new_value.hash
-        else
-          property.value(old_value) != property.value(new_value)
-        end
-
-        if dirty
-          property.hash
-          dirty_attributes[property] = property.value(new_value)
-        end
+      original_attributes.each_key do |property|
+        dirty_attributes[property] = property.value(property.get!(self))
       end
 
       dirty_attributes
     end
 
-    # Checks if the class is dirty
+    # Saves the resource
     #
-    # ==== Returns
-    # True:: returns if class is dirty
+    # @return [Boolean]
+    #   true if the resource was successfully saved
     #
-    # --
-    # @api public
-    def dirty?
-      dirty_attributes.any?
+    # @api semipublic
+    def save_self(safe = true)
+      if safe
+        new? ? create_hook : update_hook
+      else
+        new? ? _create : _update
+      end
+    end
+
+    # Saves the parent resources
+    #
+    # @return [Boolean]
+    #   true if the parents were successfully saved
+    #
+    # @api private
+    def save_parents(safe = true)
+      parent_relationships.all? do |relationship|
+        parent = relationship.get!(self)
+        if parent.dirty? ? parent.save_parents(safe) && parent.save_self(safe) : parent.saved?
+          relationship.set(self, parent)  # set the FK values
+        end
+      end
     end
 
-    # Checks if the attribute is dirty
+    # Saves the children resources
     #
-    # ==== Parameters
-    # name<Symbol>:: name of attribute
+    # @return [Boolean]
+    #   true if the children were successfully saved
     #
-    # ==== Returns
-    # True:: returns if attribute is dirty
+    # @api private
+    def save_children(safe = true)
+      child_relationships.all? do |relationship|
+        association = relationship.get!(self)
+        safe ? association.save : association.save!
+      end
+    end
+
+    # Reset the Resource to a similar state as a new record:
+    # removes it from identity map and clears original property
+    # values (thus making all properties non dirty)
     #
-    # --
-    # @api public
-    def attribute_dirty?(name)
-      dirty_attributes.has_key?(properties[name])
+    # @api private
+    def reset
+      @saved = false
+      identity_map.delete(key)
+      original_attributes.clear
+      self
     end
 
+    # Gets a Collection with the current Resource instance as its only member
+    #
+    # @return [Collection, FalseClass]
+    #   nil if this is a new record,
+    #   otherwise a Collection with self as its only member
+    #
+    # @api private
     def collection
-      @collection ||= if query = to_query
-        Collection.new(query) { |c| c << self }
-      end
+      return @collection if @collection || new? || frozen?
+      @collection = Collection.new(query, [ self ])
     end
 
-    # Reload association and all child association
+    protected
+
+    # Method for hooking callbacks on resource creation
     #
-    # ==== Returns
-    # self:: returns the class itself
+    # @return [Boolean]
+    #   true if the create was successful, false if not
     #
-    # --
-    # @api public
-    def reload
-      unless new_record?
-        reload_attributes(*loaded_attributes)
-        (parent_associations + child_associations).each { |association| association.reload }
-      end
+    # @api private
+    def create_hook
+      _create
+    end
 
-      self
+    # Method for hooking callbacks on resource updates
+    #
+    # @return [Boolean]
+    #   true if the update was successful, false if not
+    #
+    # @api private
+    def update_hook
+      _update
     end
 
-    # Reload specific attributes
+    private
+
+    # Initialize a new instance of this Resource using the provided values
     #
-    # ==== Parameters
-    # *attributes<Array[<Symbol>]>:: name of attribute
+    # @param [Hash] attributes
+    #   attribute values to use for the new instance
     #
-    # ==== Returns
-    # self:: returns the class itself
+    # @return [Hash]
+    #   attribute values used in the new instance
     #
-    # --
     # @api public
-    def reload_attributes(*attributes)
-      unless attributes.empty? || new_record?
-        collection.reload(:fields => attributes)
-      end
+    def initialize(attributes = {}, &block) # :nodoc:
+      self.attributes = attributes
+    end
 
-      self
+    # Returns name of the repository this object
+    # was loaded from
+    #
+    # @return [String]
+    #   name of the repository this object was loaded from
+    #
+    # @api private
+    def repository_name
+      repository.name
     end
 
-    # Checks if the model has been saved
+    # Gets this instance's Model's properties
     #
-    # ==== Returns
-    # True:: status if the model is new
+    # @return [Array(Property)]
+    #   List of this Resource's Model's properties
     #
-    # --
-    # @api public
-    def new_record?
-      !defined?(@new_record) || @new_record
+    # @api private
+    def properties
+      model.properties(repository_name)
     end
 
-    # all the attributes of the model
+    # Gets this instance's Model's relationships
     #
-    # ==== Returns
-    # Hash[<Symbol>]:: All the (non)-lazy attributes
+    # @return [Array(Associations::Relationship)]
+    #   List of this instance's Model's Relationships
     #
-    # --
-    # @api public
-    def attributes
-      properties.map do |p|
-        [p.name, send(p.getter)] if p.reader_visibility == :public
-      end.compact.to_hash
+    # @api private
+    def relationships
+      model.relationships(repository_name)
     end
 
-    # Mass assign of attributes
+    # Returns identity map of repository this object
+    # was loaded from
     #
-    # ==== Parameters
-    # value_hash <Hash[<Symbol>]>::
+    # @return [DataMapper::IdentityMap]
+    #   identity map of repository this object was loaded from
     #
-    # --
-    # @api public
-    def attributes=(values_hash)
-      values_hash.each do |name, value|
-        name = name.to_s.sub(/\?\z/, '')
+    # @api semipublic
+    def identity_map
+      repository.identity_map(model)
+    end
 
-        if self.class.public_method_defined?(setter = "#{name}=")
-          send(setter, value)
-        else
-          raise ArgumentError, "The property '#{name}' is not a public property."
-        end
-      end
+    # Reloads attributes that belong to given lazy loading
+    # context, and not yet loaded
+    #
+    # @api private
+    def lazy_load(property_names)
+      reload_attributes(properties.in_context(property_names) - loaded_properties)
     end
 
-    # Updates attributes and saves model
+    # Reloads specified attributes
     #
-    # ==== Parameters
-    # attributes<Hash> Attributes to be updated
-    # keys<Symbol, String, Array> keys of Hash to update (others won't be updated)
+    # @param [Enumerable(Symbol)] attributes
+    #   name(s) of attribute(s) to reload
     #
-    # ==== Returns
-    # <TrueClass, FalseClass> if model got saved or not
+    # @return [Resource]
+    #   the receiver, the current Resource instance
     #
-    #-
-    # @api public
-    def update_attributes(hash, *update_only)
-      unless hash.is_a?(Hash)
-        raise ArgumentError, "Expecting the first parameter of " +
-          "update_attributes to be a hash; got #{hash.inspect}"
+    # @api private
+    def reload_attributes(attributes)
+      unless attributes.empty? || new?
+        collection.reload(:fields => attributes)
       end
-      loop_thru = update_only.empty? ? hash.keys : update_only
-      loop_thru.each { |attr|  send("#{attr}=", hash[attr]) }
-      save
+
+      self
     end
 
-    # TODO: add docs
-    def to_query(query = {})
-      model.to_query(repository, key, query) unless new_record?
+    # Gets a Query that will return this Resource instance
+    #
+    # @return [Query]
+    #   Query that will retrieve this Resource instance
+    #
+    # @api private
+    def query
+      Query.new(repository, model, model.key_conditions(repository, key))
     end
 
-    # TODO: add docs
+    # TODO: document
     # @api private
-    def _dump(*)
-      ivars = {}
+    def parent_relationships
+      parent_relationships = []
 
-      # dump all the loaded properties
-      properties.each do |property|
-        next unless attribute_loaded?(property.name)
-        ivars[property.instance_variable_name] = property.get!(self)
-      end
+      relationships.each_value do |relationship|
+        next unless relationship.respond_to?(:resource_for) && relationship.loaded?(self)
+        next unless relationship.get(self)
 
-      # dump ivars used internally
-      %w[ @new_record @original_values @readonly @repository ].each do |name|
-        ivars[name] = instance_variable_get(name)
+        parent_relationships << relationship
       end
 
-      Marshal.dump(ivars)
+      parent_relationships
     end
 
-    protected
+    # Returns array of child relationships for which this resource is parent and is loaded
+    #
+    # @return [Array<DataMapper::Associations::OneToMany::Relationship>]
+    #   array of child relationships for which this resource is parent and is loaded
+    #
+    # @api private
+    def child_relationships
+      child_relationships = []
 
-    def properties
-      model.properties(repository.name)
-    end
+      relationships.each_value do |relationship|
+        next unless relationship.respond_to?(:collection_for) && relationship.loaded?(self)
 
-    def key_properties
-      model.key(repository.name)
-    end
+        association = relationship.get!(self)
+        next unless association.loaded? || association.head.any? || association.tail.any?
 
-    def relationships
-      model.relationships(repository.name)
+        child_relationships << relationship
+      end
+
+      many_to_many, other = child_relationships.partition do |relationship|
+        relationship.kind_of?(DataMapper::Associations::ManyToMany::Relationship)
+      end
+
+      many_to_many + other
     end
 
+    # Saves this Resource instance to the repository,
+    # setting default values for any unset properties
+    #
+    # If resource is not dirty or a new (not yet saved),
+    # this method returns false
+    #
+    # On successful save identity map of the repository is
+    # updated
+    #
     # Needs to be a protected method so that it is hookable
-    def create
+    #
+    # The primary purpose of this method is to allow before :create
+    # hooks to fire at a point just before/after resource creation
+    #
+    # @return [Boolean]
+    #   true if the receiver was successfully created
+    #
+    # @api private
+    def _create
       # Can't create a resource that is not dirty and doesn't have serial keys
-      return false if new_record? && !dirty? && !model.key.any? { |p| p.serial? }
+      return false if new? && !dirty?
+
       # set defaults for new resource
       properties.each do |property|
-        next if attribute_loaded?(property.name)
-        property.set(self, property.default_for(self))
+        unless property.serial? || property.loaded?(self)
+          property.set(self, property.default_for(self))
+        end
       end
 
-      return false unless repository.create([ self ]) == 1
+      repository.create([ self ])
 
       @repository = repository
-      @new_record = false
+      @saved      = true
+
+      original_attributes.clear
 
-      repository.identity_map(model).set(key, self)
+      identity_map[key] = self
 
       true
     end
 
-    # Needs to be a protected method so that it is hookable
-    def update
+    # Updates resource state
+    #
+    # The primary purpose of this method is to allow before :update
+    # hooks to fire at a point just before/after resource update whether
+    # it is the result of Resource#save, or using Resource#update
+    #
+    # @return [Boolean]
+    #   true if the receiver was successfully created
+    #
+    # @api private
+    def _update
       dirty_attributes = self.dirty_attributes
-      return true if dirty_attributes.empty?
-      repository.update(dirty_attributes, to_query) == 1
-    end
 
-    private
+      if dirty_attributes.empty?
+        true
+      elsif dirty_attributes.any? { |property, value| !property.nullable? && value.nil? }
+        false
+      else
+        # remove from the identity map
+        identity_map.delete(key)
 
-    def initialize(attributes = {}) # :nodoc:
-      assert_valid_model
-      self.attributes = attributes
-    end
+        return false unless repository.update(dirty_attributes, Collection.new(query, [ self ])) == 1
 
-    def assert_valid_model # :nodoc:
-      return if self.class._valid_model
-      properties = self.properties
+        # remove the cached key in case it is updated
+        remove_instance_variable(:@key)
 
-      if properties.empty? && relationships.empty?
-        raise IncompleteResourceError, "#{model.name} must have at least one property or relationship to be initialized."
-      end
-
-      if properties.key.empty?
-        raise IncompleteResourceError, "#{model.name} must have a key."
-      end
-
-      self.class.instance_variable_set("@_valid_model", true)
-    end
+        original_attributes.clear
 
-    # TODO document
-    # @api semipublic
-    def attribute_get!(name)
-      properties[name].get!(self)
-    end
+        identity_map[key] = self
 
-    # TODO document
-    # @api semipublic
-    def attribute_set!(name, value)
-      properties[name].set!(self, value)
+        true
+      end
     end
 
-    def lazy_load(name)
-      reload_attributes(*properties.lazy_load_context(name) - loaded_attributes)
-    end
+    # Return true if +other+'s is equivalent or equal to +self+'s
+    #
+    # @param [Resource] other
+    #   The Resource whose attributes are to be compared with +self+'s
+    # @param [Symbol] operator
+    #   The comparison operator to use to compare the attributes
+    #
+    # @return [Boolean]
+    #   The result of the comparison of +other+'s attributes with +self+'s
+    #
+    # @api private
+    def cmp?(other, operator)
+      return false unless key.send(operator, other.key)
+      return true if repository.send(operator, other.repository) && !dirty? && !other.dirty?
 
-    def child_associations
-      @child_associations ||= []
-    end
+      # get all the loaded and non-loaded properties that are not keys,
+      # since the key comparison was performed earlier
+      loaded, not_loaded = properties.select { |property| !property.key? }.partition do |property|
+        property.loaded?(self) && property.loaded?(other)
+      end
 
-    def parent_associations
-      @parent_associations ||= []
+      # check all loaded properties, and then all unloaded properties
+      (loaded + not_loaded).all? { |property| property.get(self).send(operator, property.get(other)) }
     end
 
-    # TODO: move to dm-more/dm-transactions
-    module Transaction
-      # Produce a new Transaction for the class of this Resource
-      #
-      # ==== Returns
-      # <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
-        model.transaction { |*block_args| yield(*block_args) }
+    # Raises an exception if #update is performed on a dirty resource
+    #
+    # @raise [UpdateConflictError]
+    #   raise if the resource is dirty
+    #
+    # @api private
+    def assert_update_clean_only(method)
+      if original_attributes.any?
+        raise UpdateConflictError, "#{model}##{method} cannot be called on a dirty resource"
       end
-    end # module Transaction
-
-    include Transaction
+    end
   end # module Resource
 end # module DataMapper