vorpal 1.0.2 → 1.3.0

data/lib/vorpal/dsl/configuration.rb

@@ -1,57 +1,154 @@
 require 'vorpal/engine'
 require 'vorpal/dsl/config_builder'
 require 'vorpal/driver/postgresql'
+require 'vorpal/config/main_config'
 
 module Vorpal
   module Dsl
-  module Configuration
-
-    # Configures and creates a {Engine} instance.
-    #
-    # @param options [Hash] Global configuration options for the engine instance.
-    # @option options [Object] :db_driver (Object that will be used to interact with the DB.)
-    #  Must be duck-type compatible with {Postgresql}.
+    # Implements the Vorpal DSL.
     #
-    # @return [Engine] Instance of the mapping engine.
-    def define(options={}, &block)
-      master_config = build_config(&block)
-      db_driver = options.fetch(:db_driver, Driver::Postgresql.new)
-      Engine.new(db_driver, master_config)
-    end
-
-    # Maps a domain class to a relational table.
+    # ```ruby
+    # engine = Vorpal.define do
+    #   map Tree do
+    #     attributes :name
+    #     belongs_to :trunk
+    #     has_many :branches
+    #   end
     #
-    # @param domain_class [Class] Type of the domain model to be mapped
-    # @param options [Hash] Configure how to map the domain model
-    # @option options [String] :to
-    #   Class of the ActiveRecord object that will map this domain class to the DB.
-    #   Optional, if one is not specified, it will be generated.
-    # @option options [Object] :serializer (map the {ConfigBuilder#attributes} directly)
-    #   Object that will convert the domain objects into a hash.
+    #   map Trunk do
+    #     attributes :length
+    #     has_one :tree
+    #   end
     #
-    #   Must have a `(Hash) serialize(Object)` method.
-    # @option options [Object] :deserializer (map the {ConfigBuilder#attributes} directly)
-    #   Object that will set a hash of attribute_names->values onto a new domain
-    #   object.
+    #   map Branch do
+    #     attributes :length
+    #     belongs_to :tree
+    #   end
+    # end
     #
-    #   Must have a `(Object) deserialize(Object, Hash)` method.
-    def map(domain_class, options={}, &block)
-      @class_configs << build_class_config(domain_class, options, &block)
-    end
+    # mapper = engine.mapper_for(Tree)
+    # ```
+    module Configuration
+      # Configures and creates a {Engine} instance.
+      #
+      # @param options [Hash] Global configuration options for the engine instance.
+      # @option options [Object] :db_driver (Object that will be used to interact with the DB.)
+      #  Must be duck-type compatible with {Postgresql}.
+      #
+      # @return [Engine] Instance of the mapping engine.
+      def define(options={}, &block)
+        @main_config = Config::MainConfig.new
+        instance_exec(&block)
+        @main_config.initialize_association_configs
+        db_driver = options.fetch(:db_driver, Driver::Postgresql.new)
+        engine = Engine.new(db_driver, @main_config)
+        @main_config = nil # make sure this MainConfig is never re-used by accident.
+        engine
+      end
 
-    # @private
-    def build_class_config(domain_class, options={}, &block)
-      builder = ConfigBuilder.new(domain_class, options, Driver::Postgresql.new)
-      builder.instance_exec(&block) if block_given?
-      builder.build
-    end
+      # Maps a domain class to a relational table.
+      #
+      # @param domain_class [Class] Type of the domain model to be mapped
+      # @param options [Hash] Configure how to map the domain model
+      # @option options [String] :to
+      #   Class of the ActiveRecord object that will map this domain class to the DB.
+      #   Optional, if one is not specified, it will be generated.
+      # @option options [Object] :serializer (map the {ConfigBuilder#attributes} directly)
+      #   Object that will convert the domain objects into a hash.
+      #
+      #   Must have a `(Hash) serialize(Object)` method.
+      # @option options [Object] :deserializer (map the {ConfigBuilder#attributes} directly)
+      #   Object that will set a hash of attribute_names->values onto a new domain
+      #   object.
+      #
+      #   Must have a `(Object) deserialize(Object, Hash)` method.
+      #  @option options [Symbol] :primary_key_type [:serial, :uuid] (:serial)
+      #    The type of primary key for the class. :serial for auto-incrementing integer, :uuid for a UUID
+      #  @option options [Symbol] :id
+      #    Same as :primary_key_type. Exists for compatibility with the Rails API.
+      def map(domain_class, options={}, &block)
+        class_config = build_class_config(domain_class, options, &block)
+        @main_config.add_class_config(class_config)
+        class_config
+      end
 
-    # @private
-    def build_config(&block)
-      @class_configs = []
-      self.instance_exec(&block)
-      MasterConfig.new(@class_configs)
+      # @private
+      def build_class_config(domain_class, options, &block)
+        @builder = ConfigBuilder.new(domain_class, options, Driver::Postgresql.new)
+        instance_exec(&block) if block_given?
+        class_config = @builder.build
+        @builder = nil # make sure this ConfigBuilder is never re-used by accident.
+        class_config
+      end
+
+      # Maps the given attributes to and from the domain object and the DB. Not needed
+      # if a serializer and deserializer were provided.
+      def attributes(*attributes)
+        @builder.attributes(*attributes)
+      end
+
+      # Defines a one-to-many association to another type where the foreign key is stored on the associated table.
+      #
+      # In Object-Oriented programming, associations are *directed*. This means that they can only be
+      # traversed in one direction: from the type that defines the association (the one with the
+      # getter) to the type that is associated.
+      #
+      # @param name [String] Name of the association getter.
+      # @param options [Hash]
+      # @option options [Boolean] :owned (True) True if the associated type belongs to the aggregate. Changes to any object belonging to the aggregate will be persisted when the aggregate is persisted.
+      # @option options [String] :fk (Association-owning class name converted to snakecase and appended with a '_id') The name of the DB column on the associated table that contains the foreign key reference to the association owner.
+      # @option options [String] :fk_type The name of the DB column on the associated table that contains the association-owning class name. Only needed when the associated end is polymorphic.
+      # @option options [String] :unique_key_name ("id") The name of the column on the owning table that the foreign key points to. Normally the primary key column.
+      # @option options [String] :primary_key Same as :unique_key_name. Exists for compatibility with Rails API.
+      # @option options [Class] :child_class DEPRECATED. Use `associated_class` instead. The associated class.
+      # @option options [Class] :associated_class (Name of the association converted to a Class) The associated class.
+      def has_many(name, options={})
+        @builder.has_many(name, options)
+      end
+
+      # Defines a one-to-one association to another type where the foreign key
+      # is stored on the associated table.
+      #
+      # In Object-Oriented programming, associations are *directed*. This means that they can only be
+      # traversed in one direction: from the type that defines the association (the one with the
+      # getter) to the type that is associated.
+      #
+      # @param name [String] Name of the association getter.
+      # @param options [Hash]
+      # @option options [Boolean] :owned (True) True if the associated type belongs to the aggregate. Changes to any object belonging to the aggregate will be persisted when the aggregate is persisted.
+      # @option options [String] :fk (Association-owning class name converted to snakecase and appended with a '_id') The name of the DB column on the associated table that contains the foreign key reference to the association owner.
+      # @option options [String] :fk_type The name of the DB column on the associated table that contains the association-owning class name. Only needed when the associated end is polymorphic.
+      # @option options [String] :unique_key_name ("id") The name of the column on the owning table that the foreign key points to. Normally the primary key column.
+      # @option options [String] :primary_key Same as :unique_key_name. Exists for compatibility with Rails API.
+      # @option options [Class] :child_class DEPRECATED. Use `associated_class` instead. The associated class.
+      # @option options [Class] :associated_class (Name of the association converted to a Class) The associated class.
+      def has_one(name, options={})
+        @builder.has_one(name, options)
+      end
+
+      # Defines a one-to-one association with another type where the foreign key
+      # is stored on the table of the entity declaring the association.
+      #
+      # This association can be polymorphic. I.E. associates can be of different types.
+      #
+      # In Object-Oriented programming, associations are *directed*. This means that they can only be
+      # traversed in one direction: from the type that defines the association (the one with the
+      # getter) to the type that is associated.
+      #
+      # @param name [String] Name of the association getter.
+      # @param options [Hash]
+      # @option options [Boolean] :owned (True) True if the associated type belongs to the aggregate. Changes to any object belonging to the aggregate will be persisted when the aggregate is persisted.
+      # @option options [String] :fk (Associated class name converted to snakecase and appended with a '_id') The name of the DB column on the association-owning table that contains the foreign key reference to the associated table.
+      # @option options [String] :fk_type The name of the DB column on the association-owning table that contains the associated class name. Only needed when the association is polymorphic.
+      # @option options [String] :unique_key_name ("id") The name of the column on the associated table that the foreign key points to. Normally the primary key column.
+      # @option options [String] :primary_key Same as :unique_key_name. Exists for compatibility with Rails API.
+      # @option options [Class] :child_class DEPRECATED. Use `associated_class` instead. The associated class.
+      # @option options [Class] :associated_class (Name of the association converted to a Class) The associated class.
+      # @option options [[Class]] :child_classes DEPRECATED. Use `associated_classes` instead. The list of possible classes that can be associated. This is for polymorphic associations. Takes precedence over `:associated_class`.
+      # @option options [[Class]] :associated_classes (Name of the association converted to a Class) The list of possible classes that can be associated. This is for polymorphic associations. Takes precedence over `:associated_class`.
+      def belongs_to(name, options={})
+        @builder.belongs_to(name, options)
+      end
     end
   end
-  end
 end

data/lib/vorpal/dsl/defaults_generator.rb

@@ -35,7 +35,7 @@ module Vorpal
       ActiveSupport::Inflector.foreign_key(name.to_s)
     end
 
-    def child_class(association_name)
+    def associated_class(association_name)
       module_parent.const_get(ActiveSupport::Inflector.classify(association_name.to_s))
     end
 

data/lib/vorpal/engine.rb

@@ -7,9 +7,9 @@ require 'vorpal/exceptions'
 module Vorpal
   class Engine
     # @private
-    def initialize(db_driver, master_config)
+    def initialize(db_driver, main_config)
       @db_driver = db_driver
-      @configs = master_config
+      @configs = main_config
     end
 
     # Creates a mapper for saving/updating/loading/destroying an aggregate to/from
@@ -34,6 +34,9 @@ module Vorpal
       serialize(all_owned_objects, mapping, loaded_db_objects)
       new_objects = get_unsaved_objects(mapping.keys)
       begin
+        # Primary keys are set eagerly (instead of waiting for them to be set by ActiveRecord upon create)
+        # because we want to support non-null FK constraints without needing to figure the correct
+        # order to save entities in.
         set_primary_keys(all_owned_objects, mapping)
         set_foreign_keys(all_owned_objects, mapping)
         remove_orphans(mapping, loaded_db_objects)
@@ -89,10 +92,16 @@ module Vorpal
       @configs.config_for(domain_class).db_class
     end
 
+    # Try to use {AggregateMapper#query} instead.
     def query(domain_class)
       @db_driver.query(@configs.config_for(domain_class).db_class, mapper_for(domain_class))
     end
 
+    # @private
+    def class_config(domain_class)
+      @configs.config_for(domain_class)
+    end
+
     private
 
     def wrap(collection_or_not)
@@ -128,8 +137,9 @@ module Vorpal
       loaded_db_objects.each do |config, db_objects|
         db_objects.each do |db_object|
           config.local_association_configs.each do |association_config|
-            db_remote = loaded_db_objects.find_by_id(
+            db_remote = loaded_db_objects.find_by_unique_key(
               association_config.remote_class_config(db_object),
+              association_config.unique_key_name,
               association_config.fk_value(db_object)
             )
             association_config.associate(identity_map.get(db_object), identity_map.get(db_remote))
@@ -150,10 +160,10 @@ module Vorpal
     def serialize_object(object, config, loaded_db_objects)
       if config.serialization_required?
         attributes = config.serialize(object)
-        if object.id.nil?
+        db_object = loaded_db_objects.find_by_primary_key(config, object)
+        if object.id.nil? || db_object.nil? # object doesn't exist in the DB
           config.build_db_object(attributes)
         else
-          db_object = loaded_db_objects.find_by_id(config, object.id)
           config.set_db_object_attributes(db_object, attributes)
           db_object
         end
@@ -165,7 +175,11 @@ module Vorpal
     def set_primary_keys(owned_objects, mapping)
       owned_objects.each do |config, objects|
         in_need_of_primary_keys = objects.find_all { |obj| obj.id.nil? }
-        primary_keys = @db_driver.get_primary_keys(config.db_class, in_need_of_primary_keys.length)
+        if config.primary_key_type == :uuid
+          primary_keys = Array.new(in_need_of_primary_keys.length) { SecureRandom.uuid }
+        elsif config.primary_key_type == :serial
+          primary_keys = @db_driver.get_primary_keys(config.db_class, in_need_of_primary_keys.length)
+        end
         in_need_of_primary_keys.zip(primary_keys).each do |object, primary_key|
           mapping[object].id = primary_key
           object.id = primary_key
@@ -179,23 +193,23 @@ module Vorpal
         objects.each do |object|
           config.has_manys.each do |has_many_config|
             if has_many_config.owned
-              children = has_many_config.get_children(object)
-              children.each do |child|
-                has_many_config.set_foreign_key(mapping[child], object)
+              associates = has_many_config.get_associated(object)
+              associates.each do |associate|
+                has_many_config.set_foreign_key(mapping[associate], object)
               end
             end
           end
 
           config.has_ones.each do |has_one_config|
             if has_one_config.owned
-              child = has_one_config.get_child(object)
-              has_one_config.set_foreign_key(mapping[child], object)
+              associate = has_one_config.get_associated(object)
+              has_one_config.set_foreign_key(mapping[associate], object) if associate
             end
           end
 
           config.belongs_tos.each do |belongs_to_config|
-            child = belongs_to_config.get_child(object)
-            belongs_to_config.set_foreign_key(mapping[object], child)
+            associate = belongs_to_config.get_associated(object)
+            belongs_to_config.set_foreign_key(mapping[object], associate)
           end
         end
       end

data/lib/vorpal/exceptions.rb

@@ -4,4 +4,8 @@ module Vorpal
   class InvalidAggregateRoot < StandardError; end
 
   class ConfigurationNotFound < StandardError; end
+
+  class ConfigurationError < StandardError; end
+
+  class InvariantViolated < StandardError; end
 end

data/lib/vorpal/identity_map.rb

@@ -28,9 +28,14 @@ module Vorpal
 
     def key(db_row)
       return nil unless db_row
-      raise "Cannot map a DB row without an id '#{db_row.inspect}' to an entity." if db_row.id.nil?
+      primary_key_value = get_primary_key_value(db_row)
+      raise "Cannot map a DB row without an id '#{db_row.inspect}' to an entity." if primary_key_value.nil?
       raise "Cannot map a DB row without a Class with a name '#{db_row.inspect}' to an entity." if db_row.class.name.nil?
-      [db_row.id, db_row.class.name]
+      [primary_key_value, db_row.class.name]
+    end
+
+    def get_primary_key_value(db_row)
+      db_row.send(db_row.class.primary_key)
     end
   end
 end

data/lib/vorpal/loaded_objects.rb

@@ -5,37 +5,80 @@ module Vorpal
 
   # @private
   class LoadedObjects
-    include Util::ArrayHash
     extend Forwardable
     include Enumerable
 
-    attr_reader :objects
-    def_delegators :objects, :each
+    def_delegators :@objects, :each
 
     def initialize
-      @objects = Hash.new([])
-      @objects_by_id = Hash.new
+      @objects = Util::ArrayHash.new
+      @cache = {}
     end
 
     def add(config, objects)
       objects_to_add = objects.map do |object|
-        if !already_loaded?(config, object.id)
-          @objects_by_id[[config.domain_class.name, object.id]] = object
+        if !already_loaded?(config, object)
+          add_to_cache(config, object)
         end
-      end
-      add_to_hash(@objects, config, objects_to_add.compact)
+      end.compact
+      @objects.append(config, objects_to_add)
+      objects_to_add
+    end
+
+    def find_by_primary_key(config, object)
+      find_by_unique_key(config, "id", object.id)
     end
 
-    def find_by_id(config, id)
-      @objects_by_id[[config.domain_class.name, id]]
+    def find_by_unique_key(config, column_name, value)
+      get_from_cache(config, column_name, value)
     end
 
     def all_objects
-      @objects_by_id.values
+      @objects.values
+    end
+
+    def already_loaded_by_unique_key?(config, column_name, id)
+      !find_by_unique_key(config, column_name, id).nil?
+    end
+
+    private
+
+    def already_loaded?(config, object)
+      !find_by_primary_key(config, object).nil?
     end
 
-    def already_loaded?(config, id)
-      !find_by_id(config, id).nil?
+    # TODO: Do we have to worry about symbols vs strings for the column_name?
+    def add_to_cache(config, object)
+      # we take a shortcut here assuming that the cache has already been primed with the primary key column
+      # because this method should always be guarded by #already_loaded?
+      column_cache = @cache[config]
+      column_cache.each do |column_name, unique_key_cache|
+        unique_key_cache[object.send(column_name)] = object
+      end
+      object
+    end
+
+    def get_from_cache(config, column_name, value)
+      lookup_hash(config, column_name)[value]
+    end
+
+    # lazily primes the cache
+    # TODO: Do we have to worry about symbols vs strings for the column_name?
+    def lookup_hash(config, column_name)
+      column_cache = @cache[config]
+      if column_cache.nil?
+        column_cache = {}
+        @cache[config] = column_cache
+      end
+      unique_key_cache = column_cache[column_name]
+      if unique_key_cache.nil?
+        unique_key_cache = {}
+        column_cache[column_name] = unique_key_cache
+        @objects[config].each do |object|
+          unique_key_cache[object.send(column_name)] = object
+        end
+      end
+      unique_key_cache
     end
   end
 end

data/lib/vorpal/util/array_hash.rb

@@ -1,19 +1,33 @@
+require 'forwardable'
+
 module Vorpal
   module Util
     # @private
-    module ArrayHash
-      def add_to_hash(array_hash, key, values)
-        if array_hash[key].nil? || array_hash[key].empty?
-          array_hash[key] = []
+    class ArrayHash
+      extend Forwardable
+
+      def_delegators :@hash, :each, :empty?, :[]
+
+      def initialize
+        @hash = Hash.new([])
+      end
+
+      def append(key, values)
+        if @hash[key].nil? || @hash[key].empty?
+          @hash[key] = []
         end
-        array_hash[key].concat(Array(values))
+        @hash[key].concat(Array(values))
       end
 
-      def pop(array_hash)
-        key = array_hash.first.first
-        values = array_hash.delete(key)
+      def pop
+        key = @hash.first.first
+        values = @hash.delete(key)
         [key, values]
       end
+
+      def values
+        @hash.values.flatten
+      end
     end
   end
 end