ghost_dm-core 1.3.0.beta

data/lib/dm-core/adapters/abstract_adapter.rb

@@ -0,0 +1,237 @@
+module DataMapper
+  module Adapters
+    # Specific adapters extend this class and implement
+    # methods for creating, reading, updating and deleting records.
+    #
+    # Adapters may only implement method for reading or (less common case)
+    # writing. Read only adapter may be useful when one needs to work
+    # with legacy data that should not be changed or web services that
+    # only provide read access to data (from Wordnet and Medline to
+    # Atom and RSS syndication feeds)
+    #
+    # Note that in case of adapters to relational databases it makes
+    # sense to inherit from DataObjectsAdapter class.
+    class AbstractAdapter
+      include DataMapper::Assertions
+      extend DataMapper::Assertions
+      extend Equalizer
+
+      equalize :name, :options, :resource_naming_convention, :field_naming_convention
+
+      # @api semipublic
+      def self.descendants
+        @descendants ||= DescendantSet.new
+      end
+
+      # @api private
+      def self.inherited(descendant)
+        descendants << descendant
+        super
+      end
+
+      # Adapter name
+      #
+      # @example
+      #   adapter.name  # => :default
+      #
+      # Note that when you use
+      #
+      # DataMapper.setup(:default, 'postgres://postgres@localhost/dm_core_test')
+      #
+      # the adapter name is currently set to :default
+      #
+      # @return [Symbol]
+      #   the adapter name
+      #
+      # @api semipublic
+      attr_reader :name
+
+      # Options with which adapter was set up
+      #
+      # @example
+      #   adapter.options  # => { :adapter => 'yaml', :path => '/tmp' }
+      #
+      # @return [Hash]
+      #   adapter configuration options
+      #
+      # @api semipublic
+      attr_reader :options
+
+      # A callable object returning a naming convention for model storage
+      #
+      # @example
+      #   adapter.resource_naming_convention  # => Proc for model storage name
+      #
+      # @return [#call]
+      #   object to return the naming convention for each model
+      #
+      # @api semipublic
+      attr_accessor :resource_naming_convention
+
+      # A callable object returning a naming convention for property fields
+      #
+      # @example
+      #   adapter.field_naming_convention  # => Proc for field name
+      #
+      # @return [#call]
+      #   object to return the naming convention for each field
+      #
+      # @api semipublic
+      attr_accessor :field_naming_convention
+
+      # Persists one or many new resources
+      #
+      # @example
+      #   adapter.create(collection)  # => 1
+      #
+      # Adapters provide specific implementation of this method
+      #
+      # @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)
+        raise NotImplementedError, "#{self.class}#create not implemented"
+      end
+
+      # Reads one or many resources from a datastore
+      #
+      # @example
+      #   adapter.read(query)  # => [ { 'name' => 'Dan Kubb' } ]
+      #
+      # Adapters provide specific implementation of this method
+      #
+      # @param [Query] query
+      #   the query to match resources in the datastore
+      #
+      # @return [Enumerable<Hash>]
+      #   an array of hashes to become resources
+      #
+      # @api semipublic
+      def read(query)
+        raise NotImplementedError, "#{self.class}#read not implemented"
+      end
+
+      # Updates one or many existing resources
+      #
+      # @example
+      #   adapter.update(attributes, collection)  # => 1
+      #
+      # Adapters provide specific implementation of this method
+      #
+      # @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)
+        raise NotImplementedError, "#{self.class}#update not implemented"
+      end
+
+      # Deletes one or many existing resources
+      #
+      # @example
+      #   adapter.delete(collection)  # => 1
+      #
+      # Adapters provide specific implementation of this method
+      #
+      # @param [Collection] collection
+      #   collection of records to be deleted
+      #
+      # @return [Integer]
+      #   the number of records deleted
+      #
+      # @api semipublic
+      def delete(collection)
+        raise NotImplementedError, "#{self.class}#delete not implemented"
+      end
+
+      # Create a Query object or subclass.
+      #
+      # Alter this method if you'd like to return an adapter specific Query subclass.
+      #
+      # @param [Repository] repository
+      #   the Repository to retrieve results from
+      # @param [Model] model
+      #   the Model to retrieve results from
+      # @param [Hash] options
+      #   the conditions and scope
+      #
+      # @return [Query]
+      #
+      # @api semipublic
+      #--
+      # TODO: DataObjects::Connection.create_command style magic (Adapter)::Query?
+      def new_query(repository, model, options = {})
+        Query.new(repository, model, options)
+      end
+
+      protected
+
+      # Set the serial value of the Resource
+      #
+      # @param [Resource] resource
+      #   the resource to set the serial property in
+      # @param [Integer] next_id
+      #   the identifier to set in the resource
+      #
+      # @return [undefined]
+      #
+      # @api semipublic
+      def initialize_serial(resource, next_id)
+        return unless serial = resource.model.serial(name)
+        return unless serial.get!(resource).nil?
+        serial.set!(resource, next_id)
+
+        # TODO: replace above with this, once
+        # specs can handle random, non-sequential ids
+        #serial.set!(resource, rand(2**32))
+      end
+
+      # Translate the attributes into a Hash with the field as the key
+      #
+      # @example
+      #   attributes = { User.properties[:name] => 'Dan Kubb' }
+      #   adapter.attributes_as_fields(attributes)  # => { 'name' => 'Dan Kubb' }
+      #
+      # @param [Hash] attributes
+      #   the attributes with the Property as the key
+      #
+      # @return [Hash]
+      #   the attributes with the Property#field as the key
+      #
+      # @api semipublic
+      def attributes_as_fields(attributes)
+        Hash[ attributes.map { |property, value| [ property.field, property.dump(value) ] } ]
+      end
+
+      private
+
+      # Initialize an AbstractAdapter instance
+      #
+      # @param [Symbol] name
+      #   the adapter repository name
+      # @param [Hash] options
+      #   the adapter configuration options
+      #
+      # @return [undefined]
+      #
+      # @api semipublic
+      def initialize(name, options)
+        @name                       = name
+        @options                    = options.dup.freeze
+        @resource_naming_convention = NamingConventions::Resource::UnderscoredAndPluralized
+        @field_naming_convention    = NamingConventions::Field::Underscored
+      end
+    end # class AbstractAdapter
+
+    const_added(:AbstractAdapter)
+  end # module Adapters
+end # module DataMapper

data/lib/dm-core/adapters/in_memory_adapter.rb

@@ -0,0 +1,113 @@
+module DataMapper
+  module Adapters
+    # This is probably the simplest functional adapter possible. It simply
+    # stores and queries from a hash containing the model classes as keys,
+    # and an array of hashes. It is not persistent whatsoever; when the Ruby
+    # process finishes, everything that was stored it lost. However, it doesn't
+    # require any other external libraries, such as data_objects, so it is ideal
+    # for writing specs against. It also serves as an excellent example for
+    # budding adapter developers, so it is critical that it remains well documented
+    # and up to date.
+    class InMemoryAdapter < AbstractAdapter
+      # Used by DataMapper to put records into a data-store: "INSERT" in SQL-speak.
+      # It takes an array of the resources (model instances) to be saved. Resources
+      # each have a key that can be used to quickly look them up later without
+      # searching, if the adapter supports it.
+      #
+      # @param [Enumerable(Resource)] resources
+      #   The set of resources (model instances)
+      #
+      # @api semipublic
+      def create(resources)
+        records = records_for(resources.first.model)
+
+        resources.each do |resource|
+          initialize_serial(resource, records.size.succ)
+          records << attributes_as_fields(resource.attributes(nil))
+        end
+      end
+
+      # Looks up one record or a collection of records from the data-store:
+      # "SELECT" in SQL.
+      #
+      # @param [Query] query
+      #   The query to be used to seach for the resources
+      #
+      # @return [Array]
+      #   An Array of Hashes containing the key-value pairs for
+      #   each record
+      #
+      # @api semipublic
+      def read(query)
+        query.filter_records(records_for(query.model).dup)
+      end
+
+      # Used by DataMapper to update the attributes on existing records in a
+      # data-store: "UPDATE" in SQL-speak. It takes a hash of the attributes
+      # to update with, as well as a collection object that specifies which resources
+      # should be updated.
+      #
+      # @param [Hash] attributes
+      #   A set of key-value pairs of the attributes to update the resources with.
+      # @param [DataMapper::Collection] resources
+      #   The collection of resources to update.
+      #
+      # @api semipublic
+      def update(attributes, collection)
+        attributes = attributes_as_fields(attributes)
+        read(collection.query).each { |record| record.update(attributes) }.size
+      end
+
+      # Destroys all the records matching the given query. "DELETE" in SQL.
+      #
+      # @param [DataMapper::Collection] resources
+      #   The collection of resources to delete.
+      #
+      # @return [Integer]
+      #   The number of records that were deleted.
+      #
+      # @api semipublic
+      def delete(collection)
+        records = records_for(collection.model)
+        records_to_delete = collection.query.filter_records(records.dup)
+        records.replace(records - records_to_delete)
+        records_to_delete.size
+      end
+
+      # TODO consider proper automigrate functionality
+      def reset
+        @records = {}
+      end
+
+      private
+
+      # Make a new instance of the adapter. The @records ivar is the 'data-store'
+      # for this adapter. It is not shared amongst multiple incarnations of this
+      # adapter, eg DataMapper.setup(:default, :adapter => :in_memory);
+      # DataMapper.setup(:alternate, :adapter => :in_memory) do not share the
+      # data-store between them.
+      #
+      # @param [String, Symbol] name
+      #   The name of the Repository using this adapter.
+      # @param [String, Hash] uri_or_options
+      #   The connection uri string, or a hash of options to set up
+      #   the adapter
+      #
+      # @api semipublic
+      def initialize(name, options = {})
+        super
+        @records = {}
+      end
+
+      # All the records we're storing. This method will look them up by model name
+      #
+      # @api private
+      def records_for(model)
+        @records[model.storage_name(name)] ||= []
+      end
+
+    end # class InMemoryAdapter
+
+    const_added(:InMemoryAdapter)
+  end # module Adapters
+end # module DataMapper

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

@@ -0,0 +1,499 @@
+module DataMapper
+  module Associations
+    module ManyToMany #:nodoc:
+      class Relationship < Associations::OneToMany::Relationship
+        extend Chainable
+
+        OPTIONS = superclass::OPTIONS.dup << :through << :via
+
+        # Returns a set of keys that identify the target model
+        #
+        # @return [DataMapper::PropertySet]
+        #   a set of properties that identify the target model
+        #
+        # @api semipublic
+        def child_key
+          return @child_key if defined?(@child_key)
+
+          repository_name = child_repository_name || parent_repository_name
+          properties      = child_model.properties(repository_name)
+
+          @child_key = if @child_properties
+            child_key = properties.values_at(*@child_properties)
+            properties.class.new(child_key).freeze
+          else
+            properties.key
+          end
+        end
+
+        # @api semipublic
+        alias_method :target_key, :child_key
+
+        # Intermediate association for through model
+        # relationships
+        #
+        # Example: for :bugs association in
+        #
+        # class Software::Engineer
+        #   include DataMapper::Resource
+        #
+        #   has n, :missing_tests
+        #   has n, :bugs, :through => :missing_tests
+        # end
+        #
+        # through is :missing_tests
+        #
+        # TODO: document a case when
+        # through option is a model and
+        # not an association name
+        #
+        # @api semipublic
+        def through
+          return @through if defined?(@through)
+
+          @through = options[:through]
+
+          if @through.kind_of?(Associations::Relationship)
+            return @through
+          end
+
+          model           = source_model
+          repository_name = source_repository_name
+          relationships   = model.relationships(repository_name)
+          name            = through_relationship_name
+
+          @through = relationships[name] ||
+            DataMapper.repository(repository_name) do
+              model.has(min..max, name, through_model, one_to_many_options)
+            end
+
+          @through.child_key
+
+          @through
+        end
+
+        # @api semipublic
+        def via
+          return @via if defined?(@via)
+
+          @via = options[:via]
+
+          if @via.kind_of?(Associations::Relationship)
+            return @via
+          end
+
+          name            = self.name
+          through         = self.through
+          repository_name = through.relative_target_repository_name
+          through_model   = through.target_model
+          relationships   = through_model.relationships(repository_name)
+          singular_name   = DataMapper::Inflector.singularize(name.to_s).to_sym
+
+          @via = relationships[@via] ||
+            relationships[name]      ||
+            relationships[singular_name]
+
+          @via ||= if anonymous_through_model?
+            DataMapper.repository(repository_name) do
+              through_model.belongs_to(singular_name, target_model, many_to_one_options)
+            end
+          else
+            raise UnknownRelationshipError, "No relationships named #{name} or #{singular_name} in #{through_model}"
+          end
+
+          @via.child_key
+
+          @via
+        end
+
+        # @api semipublic
+        def links
+          return @links if defined?(@links)
+
+          @links = []
+          links  = [ through, via ]
+
+          while relationship = links.shift
+            if relationship.respond_to?(:links)
+              links.unshift(*relationship.links)
+            else
+              @links << relationship
+            end
+          end
+
+          @links.freeze
+        end
+
+        # Initialize the chain for "many to many" relationships
+        #
+        # @return [self]
+        #
+        # @api public
+        def finalize
+          through
+          via
+          self
+        end
+
+        # @api private
+        def source_scope(source)
+          { through.inverse => source }
+        end
+
+        # @api private
+        def query
+          # TODO: consider making this a query_for method, so that ManyToMany::Relationship#query only
+          # returns the query supplied in the definition
+          @many_to_many_query ||= super.merge(:links => links).freeze
+        end
+
+        # Eager load the collection using the source as a base
+        #
+        # @param [Resource, Collection] source
+        #   the source to query with
+        # @param [Query, Hash] other_query
+        #   optional query to restrict the collection
+        #
+        # @return [ManyToMany::Collection]
+        #   the loaded collection for the source
+        #
+        # @api private
+        def eager_load(source, other_query = nil)
+          # FIXME: enable SEL for m:m relationships
+          source.model.all(query_for(source, other_query))
+        end
+
+        private
+
+        # @api private
+        def through_model
+          namespace, name = through_model_namespace_name
+
+          if namespace.const_defined?(name)
+            namespace.const_get(name)
+          else
+            Model.new(name, namespace) do
+              # all properties added to the anonymous through model are keys
+              def property(name, type, options = {})
+                options[:key] = true
+                options.delete(:index)
+                super
+              end
+            end
+          end
+        end
+
+        # @api private
+        def through_model_namespace_name
+          target_parts = target_model.base_model.name.split('::')
+          source_parts = source_model.base_model.name.split('::')
+
+          name = [ target_parts.pop, source_parts.pop ].sort.join
+
+          namespace = Object
+
+          # find the common namespace between the target_model and source_model
+          target_parts.zip(source_parts) do |target_part, source_part|
+            break if target_part != source_part
+            namespace = namespace.const_get(target_part)
+          end
+
+          return namespace, name
+        end
+
+        # @api private
+        def through_relationship_name
+          if anonymous_through_model?
+            namespace = through_model_namespace_name.first
+            relationship_name = DataMapper::Inflector.underscore(through_model.name.sub(/\A#{namespace.name}::/, '')).tr('/', '_')
+            DataMapper::Inflector.pluralize(relationship_name).to_sym
+          else
+            options[:through]
+          end
+        end
+
+        # Check if the :through association uses an anonymous model
+        #
+        # An anonymous model means that DataMapper creates the model
+        # in-memory, and sets the relationships to join the source
+        # and the target model.
+        #
+        # @return [Boolean]
+        #   true if the through model is anonymous
+        #
+        # @api private
+        def anonymous_through_model?
+          options[:through] == Resource
+        end
+
+        # @api private
+        def nearest_relationship
+          return @nearest_relationship if defined?(@nearest_relationship)
+
+          nearest_relationship = self
+
+          while nearest_relationship.respond_to?(:through)
+            nearest_relationship = nearest_relationship.through
+          end
+
+          @nearest_relationship = nearest_relationship
+        end
+
+        # @api private
+        def valid_target?(target)
+          relationship = via
+          source_key   = relationship.source_key
+          target_key   = relationship.target_key
+
+          target.kind_of?(target_model) &&
+          source_key.valid?(target_key.get(target))
+        end
+
+        # @api private
+        def valid_source?(source)
+          relationship = nearest_relationship
+          source_key   = relationship.source_key
+          target_key   = relationship.target_key
+
+          source.kind_of?(source_model) &&
+          target_key.valid?(source_key.get(source))
+        end
+
+        chainable do
+          # @api semipublic
+          def many_to_one_options
+            { :parent_key => target_key.map { |property| property.name } }
+          end
+
+          # @api semipublic
+          def one_to_many_options
+            { :parent_key => source_key.map { |property| property.name } }
+          end
+        end
+
+        # Returns the inverse relationship class
+        #
+        # @api private
+        def inverse_class
+          self.class
+        end
+
+        # @api private
+        def invert
+          inverse_class.new(inverse_name, parent_model, child_model, inverted_options)
+        end
+
+        # @api private
+        def inverted_options
+          links   = self.links.dup
+          through = links.pop.inverse
+
+          links.reverse_each do |relationship|
+            inverse = relationship.inverse
+
+            through = self.class.new(
+              inverse.name,
+              inverse.child_model,
+              inverse.parent_model,
+              inverse.options.merge(:through => through)
+            )
+          end
+
+          options = self.options
+
+          DataMapper::Ext::Hash.only(options, *OPTIONS - [ :min, :max ]).update(
+            :through    => through,
+            :child_key  => options[:parent_key],
+            :parent_key => options[:child_key],
+            :inverse    => self
+          )
+        end
+
+        # Returns collection class used by this type of
+        # relationship
+        #
+        # @api private
+        def collection_class
+          ManyToMany::Collection
+        end
+      end # class Relationship
+
+      class Collection < Associations::OneToMany::Collection
+        # Remove every Resource in the m:m Collection from the repository
+        #
+        # This performs a deletion of each Resource in the Collection from
+        # the repository and clears the Collection.
+        #
+        # @return [Boolean]
+        #   true if the resources were successfully destroyed
+        #
+        # @api public
+        def destroy
+          assert_source_saved 'The source must be saved before mass-deleting the collection'
+
+          # make sure the records are loaded so they can be found when
+          # the intermediaries are removed
+          lazy_load
+
+          unless intermediaries.all(via => self).destroy
+            return false
+          end
+
+          super
+        end
+
+        # Remove every Resource in the m:m Collection from the repository, bypassing validation
+        #
+        # This performs a deletion of each Resource in the Collection from
+        # the repository and clears the Collection while skipping
+        # validation.
+        #
+        # @return [Boolean]
+        #   true if the resources were successfully destroyed
+        #
+        # @api public
+        def destroy!
+          assert_source_saved 'The source must be saved before mass-deleting the collection'
+
+          model      = self.model
+          key        = model.key(repository_name)
+          conditions = Query.target_conditions(self, key, key)
+
+          unless intermediaries.all(via => self).destroy!
+            return false
+          end
+
+          unless model.all(:repository => repository, :conditions => conditions).destroy!
+            return false
+          end
+
+          each do |resource|
+            resource.persistence_state = Resource::PersistenceState::Immutable.new(resource)
+          end
+
+          clear
+
+          true
+        end
+
+        # Return the intermediaries linking the source to the targets
+        #
+        # @return [Collection]
+        #   the intermediary collection
+        #
+        # @api public
+        def intermediaries
+          through = self.through
+          source  = self.source
+
+          @intermediaries ||= if through.loaded?(source)
+            through.get_collection(source)
+          else
+            reset_intermediaries
+          end
+        end
+
+        protected
+
+        # Map the resources in the collection to the intermediaries
+        #
+        # @return [Hash]
+        #   the map of resources to their intermediaries
+        #
+        # @api private
+        def intermediary_for
+          @intermediary_for ||= {}
+        end
+
+        # @api private
+        def through
+          relationship.through
+        end
+
+        # @api private
+        def via
+          relationship.via
+        end
+
+        private
+
+        # @api private
+        def _create(attributes, execute_hooks = true)
+          via = self.via
+          if via.respond_to?(:resource_for)
+            resource = super
+            if create_intermediary(execute_hooks, resource)
+              resource
+            end
+          else
+            if intermediary = create_intermediary(execute_hooks)
+              super(attributes.merge(via.inverse => intermediary), execute_hooks)
+            end
+          end
+        end
+
+        # @api private
+        def _save(execute_hooks = true)
+          via = self.via
+
+          if @removed.any?
+            # delete only intermediaries linked to the removed targets
+            return false unless intermediaries.all(via => @removed).send(execute_hooks ? :destroy : :destroy!)
+
+            # reset the intermediaries so that it reflects the current state of the datastore
+            reset_intermediaries
+          end
+
+          loaded_entries = self.loaded_entries
+
+          if via.respond_to?(:resource_for)
+            super
+            loaded_entries.all? { |resource| create_intermediary(execute_hooks, resource) }
+          else
+            if loaded_entries.any? && (intermediary = create_intermediary(execute_hooks))
+              inverse = via.inverse
+              loaded_entries.each { |resource| inverse.set(resource, intermediary) }
+            end
+
+            super
+          end
+        end
+
+        # @api private
+        def create_intermediary(execute_hooks, resource = nil)
+          intermediary_for = self.intermediary_for
+
+          intermediary_resource = intermediary_for[resource]
+          return intermediary_resource if intermediary_resource
+
+          intermediaries = self.intermediaries
+          method         = execute_hooks ? :save : :save!
+
+          return unless intermediaries.send(method)
+
+          attributes = {}
+          attributes[via] = resource if resource
+
+          intermediary = intermediaries.first_or_new(attributes)
+          return unless intermediary.__send__(method)
+
+          # map the resource, even if it is nil, to the intermediary
+          intermediary_for[resource] = intermediary
+        end
+
+        # @api private
+        def reset_intermediaries
+          through = self.through
+          source  = self.source
+
+          through.set_collection(source, through.collection_for(source))
+        end
+
+        # @api private
+        def inverse_set(*)
+          # do nothing
+        end
+      end # class Collection
+    end # module ManyToMany
+  end # module Associations
+end # module DataMapper