datamapper-dm-core 0.9.11 → 0.10.0

data/lib/dm-core/repository.rb

@@ -1,167 +1,207 @@
 module DataMapper
   class Repository
-    include Assertions
+    include Extlib::Assertions
+    extend Equalizer
 
-    @adapters = {}
+    equalize :name, :adapter
 
-    ##
+    # Get the list of adapters registered for all Repositories,
+    # keyed by repository name.
     #
-    # @return <Adapter> the adapters registered for this repository
+    #   TODO: create example
+    #
+    # @return [Hash(Symbol => Adapters::AbstractAdapter)]
+    #   the adapters registered for all Repositories
+    #
+    # @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)
-    end
-
-    def update(attributes, query)
-      adapter.update(attributes, query)
-    end
-
-    def delete(query)
-      adapter.delete(query)
-    end
-
-    def eql?(other)
-      return true if super
-      name == other.name
+    # @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
 
-    alias == eql?
-
-    def to_s
-      "#<DataMapper::Repository:#{@name}>"
+    # 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 _dump(*)
-      name.to_s
+    # 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
 
-    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
 
       @name          = name
       @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)
-      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)
-      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
-    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