datamappify 0.50.0 → 0.51.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 51bd14425d7e0347cf2a97adff354cb262038152
-  data.tar.gz: f7fc7a27a71d6e5cb10c971f9a7e57fc968ac8d0
+  metadata.gz: f9765005a9b047c0dabab75eeb3da7997761c57d
+  data.tar.gz: c6747c591e913b7565a730ea7192703991aaf2b6
 SHA512:
-  metadata.gz: ef748d505249785e6da9518a05eaab78cca206517eb708900e43e4342bedf01be6f2c369f1570058866dc10a7ac4c7a560b5ddb0371c4b35e0a6b3abdc2e2eaf
-  data.tar.gz: e7a1d50c78433c4945b06507ad60fe366f7f9623fa806cafbf54a3b99229232dafca583ea31e1d3a827729eeffcf108f4712e607b5f80fde005abf66782885e4
+  metadata.gz: 64566dfe4f603db5104657ca9416aef1d96f4b0327de25c0c9a36a68285b3dcf049efd2c39381f5f4f2ab7b781509c13f0c4ef27b02066e9b634e5cd23c56720
+  data.tar.gz: 0bc81a94c2c52c1b3da152d79f39405be5050e2242c526d628650591a4e741250f5d47136c93ef96a2a1f63f6c264200754ad603ea41954aafaffb2ce2f91cda

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## master
 
+## 0.51.0 [2013-06-17]
+
+- Enhanced `find` for searching specific attributes.
+- Added support for repository inheritance.
+- `attributes_from` now copies validations as well!
+- `find` now raises an exception if the arguments contain an unknown attribute key.
+
 ## 0.50.0 [2013-05-30]
 
 - Added `all` to repository.

data/README.md

@@ -50,16 +50,50 @@ class User
   attribute :driver_license, String
   attribute :health_care,    String
 
-  # Nested entity composition - composing the entity with attributes from other entities
+  # Nested entity composition - composing the entity with attributes and validations from other entities
+  #
+  #   class Job
+  #     include Datamappify::Entity
+  #
+  #     attributes :title, String
+  #     validates  :title, :presence => true
+  #   end
+  #
+  #   class User
+  #     # ...
+  #     attributes_from Job
+  #   end
+  #
+  # essentially equals:
+  #
+  #   class User
+  #     # ...
+  #     attributes :title, String
+  #     validates  :title, :presence => true
+  #   end
   attributes_from Job
 
   # optionally you may prefix the attributes, so that:
   #
-  #   :programming
+  #   class Hobby
+  #     include Datamappify::Entity
+  #
+  #     attributes :name, String
+  #     validates  :name, :presence => true
+  #   end
+  #
+  #   class User
+  #     # ...
+  #     attributes_from Hobby, :prefix_with => :hobby
+  #   end
   #
   # becomes:
   #
-  #   :hobby_programming
+  #   class User
+  #     # ...
+  #     attributes :hobby_name, String
+  #     validates  :hobby_name, :presence => true
+  #   end
   attributes_from Hobby, :prefix_with => :hobby
 
   # Entity reference
@@ -85,6 +119,18 @@ class User
 end
 ```
 
+Inheritance is supported for entities, for example:
+
+```ruby
+class AdminUser < User
+  attribute :level, Integer
+end
+
+class GuestUser < User
+  attribute :expiry, DateTime
+end
+```
+
 #### Lazy loading
 
 Datamappify supports attribute lazy loading via the `Lazy` module.
@@ -126,6 +172,24 @@ class UserRepository
 end
 ```
 
+Inheritance is supported for repositories when your data structure is based on STI ([Single Table Inheritance](http://en.wikipedia.org/wiki/Single_Table_Inheritance)), for example:
+
+```ruby
+class AdminUserRepository < UserRepository
+  for_entity AdminUser
+end
+
+class GuestUserRepository < UserRepository
+  for_entity GuestUser
+
+  map_attribute :expiry, 'ActiveRecord::User#expiry_date'
+end
+```
+
+In the above example, both repositories deal with the `User` data model.
+
+### Repository APIs
+
 _More repository APIs are being added, below is a list of the currently implemented APIs._
 
 #### Retrieving an entity
@@ -146,12 +210,22 @@ UserRepository.exists?(user)
 
 #### Retrieving all entities
 
-Returns an array of user entities.
+Returns an array of entities.
 
 ```ruby
 users = UserRepository.all
 ```
 
+#### Searching entities
+
+Returns an array of entities.
+
+```ruby
+users = UserRepository.find(:first_name => 'Fred', :driver_license => 'AABBCCDD')
+```
+
+_Note: it does not currently support searching attributes from different data providers._
+
 #### Saving/updating entities
 
 Pass in an entity.

data/lib/datamappify/data/criteria/active_record/find_multiple.rb

@@ -5,6 +5,34 @@ module Datamappify
     module Criteria
       module ActiveRecord
         class FindMultiple < Relational::FindMultiple
+          private
+
+          # @return [Array]
+          def records
+            source_class.joins(@secondaries.map(&:source_key)).where(
+              structured_criteria(primaries, secondaries)
+            )
+          end
+
+          # @param primaries [Array<Attribute>]
+          #
+          # @param secondaries [Array<Attribute>]
+          #
+          # @return [Hash]
+          def structured_criteria(primaries, secondaries)
+            _criteria = {}
+
+            primaries.each do |primary|
+              _criteria[primary.source_attribute_key] = primary.value
+            end
+
+            secondaries.each do |secondary|
+              _criteria[secondary.source_table] ||= {}
+              _criteria[secondary.source_table][secondary.source_attribute_key] = secondary.value
+            end
+
+            _criteria
+          end
         end
       end
     end

data/lib/datamappify/data/criteria/common.rb

@@ -41,11 +41,19 @@ module Datamappify
 
         protected
 
+        # Name of the default source class, e.g. +"User"+,
+        # it is determined from either the PK or the entity
+        #
+        # @return [String]
+        def default_source_class_name
+          @default_source_class_name ||= pk ? pk.source_class_name : entity.class.name.demodulize
+        end
+
         # Key name of either the primary key (e.g. +id+) or foreign key (e.g. +user_id+)
         #
         # @return [Symbol]
         def key_name
-          primary_record? ? :id : "#{entity.class.name.demodulize.underscore}_id".to_sym
+          primary_record? ? :id : any_attribute.primary_reference_key
         end
 
         # The value of {#key_name}
@@ -66,7 +74,7 @@ module Datamappify
         #
         # @return [Boolean]
         def primary_record?
-          source_class.name.demodulize == entity.class.name.demodulize
+          source_class.name.demodulize == default_source_class_name
         end
 
         # Ignores the current Criteria's operation if there is no dirty attributes
@@ -80,15 +88,17 @@ module Datamappify
         #
         # @return [Hash]
         def attributes_and_values
-          hash = {}
+          @attributes_and_values ||= begin
+            hash = {}
 
-          attributes.each do |attribute|
-            unless ignore_attribute?(attribute)
-              hash[attribute.source_attribute_name] = entity.send(attribute.name)
+            attributes.each do |attribute|
+              unless ignore_attribute?(attribute)
+                hash[attribute.source_attribute_name] = entity.send(attribute.name)
+              end
             end
-          end
 
-          hash
+            hash
+          end
         end
 
         # Stores the attribute value in {Mapper::Attribute} for later use
@@ -100,6 +110,16 @@ module Datamappify
           end
         end
 
+        # @return [Attribute]
+        def any_attribute
+          @any_attribute ||= attributes.first
+        end
+
+        # @return [Attribute]
+        def pk
+          @pk ||= attributes.find { |attribute| attribute.key == :id }
+        end
+
         private
 
         # Ignores the attribute if it isn't dirty or if it's a primary key

data/lib/datamappify/data/criteria/relational/find_multiple.rb

@@ -5,8 +5,22 @@ module Datamappify
         class FindMultiple < Common
           alias_method :entity_class, :entity
 
+          attr_reader :primaries, :secondaries, :structured_criteria
+
+          def initialize(*args)
+            super
+
+            @primaries   = []
+            @secondaries = []
+
+            updated_attributes.each do |attribute|
+              collector = attribute.primary_attribute? ? @primaries : @secondaries
+              collector << attribute
+            end
+          end
+
+          # @return [void]
           def perform
-            records = source_class.where(criteria)
             records.map do |record|
               entity = entity_class.new
               update_entity(entity, record)
@@ -16,11 +30,56 @@ module Datamappify
 
           private
 
-          def update_entity(entity, record)
+          # @return [Array]
+          def updated_attributes
+            unless criteria.keys & attributes.map(&:key) == criteria.keys
+              raise EntityAttributeInvalid
+            end
+
+            @updated_attributes ||= attributes.select do |attribute|
+              attribute.value = criteria[attribute.key]
+              criteria.keys.include?(attribute.key)
+            end
+          end
+
+          # @param entity [Entity]
+          #
+          # @param record [Class]
+          #
+          # @return [void]
+          def update_entity(entity, primary_record)
             attributes.each do |attribute|
-              entity.send("#{attribute.name}=", record.send(attribute.source_attribute_name))
+              record = data_record_for(attribute, primary_record)
+              value  = record_value_for(attribute, record)
+
+              entity.send("#{attribute.name}=", value)
+            end
+          end
+
+          # @param attribute [Attribute]
+          #
+          # @param primary_record [Class]
+          #   an ORM model object (ActiveRecord or Sequel, etc)
+          #
+          # @return [Object]
+          #   an ORM model object (ActiveRecord or Sequel, etc)
+          def data_record_for(attribute, primary_record)
+            if attribute.primary_attribute?
+              primary_record
+            else
+              primary_record.send(attribute.source_key)
             end
           end
+
+          # @param attribute [Attribute]
+          #
+          # @param record [Class]
+          #   an ORM model object (ActiveRecord or Sequel, etc)
+          #
+          # @return [any]
+          def record_value_for(attribute, record)
+            record.nil? ? nil : record.send(attribute.source_attribute_name)
+          end
         end
       end
     end

data/lib/datamappify/data/criteria/sequel/find_multiple.rb

@@ -5,6 +5,37 @@ module Datamappify
     module Criteria
       module Sequel
         class FindMultiple < Relational::FindMultiple
+          private
+
+          # @return [Array]
+          def records
+            query_builder = source_class
+
+            secondaries.each do |secondary|
+              query_builder = query_builder.join(secondary.source_table, secondary.primary_reference_key => :id)
+            end
+
+            query_builder.where(structured_criteria(primaries, secondaries))
+          end
+
+          # @param primaries [Array<Attribute>]
+          #
+          # @param secondaries [Array<Attribute>]
+          #
+          # @return [Hash]
+          def structured_criteria(primaries, secondaries)
+            _criteria = {}
+
+            primaries.each do |primary|
+              _criteria[primary.source_attribute_key] = primary.value
+            end
+
+            secondaries.each do |secondary|
+              _criteria[:"#{secondary.source_table}__#{secondary.source_attribute_name}"] = secondary.value
+            end
+
+            _criteria
+          end
         end
       end
     end

data/lib/datamappify/data/errors.rb

@@ -18,5 +18,8 @@ module Datamappify
 
     class EntityNotDestroyed < Error
     end
+
+    class EntityAttributeInvalid < Error
+    end
   end
 end

data/lib/datamappify/data/mapper/attribute.rb

@@ -20,6 +20,9 @@ module Datamappify
         # @return [String]
         attr_reader :source_attribute_name
 
+        # @return [Class]
+        attr_reader :primary_source_class
+
         # @return [any]
         attr_accessor :value
 
@@ -29,23 +32,98 @@ module Datamappify
         # @param source [String]
         #   data provider, class and attribute,
         #   e.g. "ActiveRecord::User#surname"
-        def initialize(name, source)
-          @key  = name
-          @name = name.to_s
+        #
+        # @param primary_source_class [Class]
+        def initialize(name, source, primary_source_class)
+          @key                  = name
+          @name                 = name.to_s
+          @primary_source_class = primary_source_class
 
           @provider_name, @source_class_name, @source_attribute_name = parse_source(source)
+
+          unless primary_attribute? || external_attribute?
+            Record.build_association(self, primary_source_class)
+          end
         end
 
+        # @example
+        #
+        #   UserComment
+        #
         # @return [Class]
         def source_class
           @source_class ||= Record.find_or_build(provider_name, source_class_name)
         end
 
+        # @example
+        #
+        #   "user_comment"
+        #
+        # @return [String]
+        def source_name
+          @source_name ||= source_class_name.underscore
+        end
+
+        # @example
+        #
+        #   :user_comment
+        #
+        # @return [Symbol]
+        def source_key
+          @source_key ||= source_name.to_sym
+        end
+
+        # @example
+        #
+        #   :title
+        #
+        # @return [Symbol]
+        def source_attribute_key
+          @source_attribute_key ||= source_attribute_name.to_sym
+        end
+
+        # @example
+        #
+        #   :user_comments
+        #
+        # @return [Symbol]
+        def source_table
+          @source_table ||= source_class_name.pluralize.underscore.to_sym
+        end
+
         # @return [Boolean]
         def primary_key?
           source_attribute_name == 'id'
         end
 
+        # @return [Boolean]
+        def primary_attribute?
+          provider_name == primary_provider_name && primary_source_class == source_class
+        end
+
+        # External attribute is from a different data provider than the primary data provider
+        #
+        # @return [Boolean]
+        def external_attribute?
+          provider_name != primary_provider_name
+        end
+
+        # @return [String]
+        def primary_provider_name
+          @primary_provider_name ||= primary_source_class.parent.to_s.demodulize
+        end
+
+        # Foreign key of the primary record, useful for joins
+        #
+        # @example
+        #
+        #   :user_id
+        #
+        # @return [Symbol]
+        def primary_reference_key
+          @primary_reference_key ||= :"#{primary_source_class.to_s.demodulize.underscore}_id"
+        end
+
         private
 
         # @return [Array<String>]

data/lib/datamappify/data/mapper.rb

@@ -10,6 +10,9 @@ module Datamappify
       # @return [String]
       attr_accessor :default_provider_name
 
+      # @return [String]
+      attr_writer :default_source_class_name
+
       # @return [Hash]
       #   attribute name to source mapping as specified in {Repository::MappingDSL#map_attribute}
       attr_accessor :custom_mapping
@@ -24,6 +27,8 @@ module Datamappify
         @default_provider ||= Provider.const_get(default_provider_name)
       end
 
+      # @param provider_name [String]
+      #
       # @return [Module]
       def provider(provider_name)
         Provider.const_get(provider_name)
@@ -31,12 +36,12 @@ module Datamappify
 
       # @return [Class]
       def default_source_class
-        @default_source_class ||= default_provider.find_or_build_record_class(entity_class.name)
+        @default_source_class ||= default_provider.find_or_build_record_class(default_source_class_name)
       end
 
       # @return [String]
       def default_source_class_name
-        entity_class.name
+        @default_source_class_name ||= entity_class.name
       end
 
       # @return [Set<Attribute>]
@@ -50,11 +55,6 @@ module Datamappify
         @classified_attributes ||= Set.new(attributes).classify(&:provider_name)
       end
 
-      # @return [Array<Attribute>]
-      def attributes_from_default_source
-        classified_attributes[default_provider_name].classify(&:source_class_name)[default_source_class_name]
-      end
-
       private
 
       # @return [Array<Symbol>]
@@ -78,24 +78,24 @@ module Datamappify
       # @return [Array<Attribute>]
       def default_attributes
         @default_attributes ||= default_attribute_names.collect do |attribute|
-          Attribute.new(attribute, default_source_for(attribute))
+          Attribute.new(attribute, default_source_for(attribute), default_source_class)
         end
       end
 
       # @return [Array<Attribute>]
       def custom_attributes
         @custom_attributes ||= custom_mapping.collect do |attribute, source|
-          map_attribute(attribute, source)
+          map_custom_attribute(attribute, source)
         end
       end
 
       # @param (see Data::Mapper::Attribute#initialize)
       #
       # @return [Attribute]
-      def map_attribute(name, source)
+      def map_custom_attribute(name, source)
         @custom_attribute_names << name
 
-        Attribute.new(name, source)
+        Attribute.new(name, source, default_source_class)
       end
 
       # @param attribute [Symbol]
@@ -103,7 +103,7 @@ module Datamappify
       #
       # @return [String]
       def default_source_for(attribute)
-        "#{default_provider_name}::#{entity_class.name}##{attribute}"
+        "#{default_provider_name}::#{default_source_class_name}##{attribute}"
       end
     end
   end

data/lib/datamappify/data/provider/active_record.rb

@@ -4,11 +4,26 @@ module Datamappify
       module ActiveRecord
         extend CommonProvider
 
-        # @return [ActiveRecord::Base]
-        def self.build_record_class(source_class_name)
-          Datamappify::Data::Record::ActiveRecord.const_set(
-            source_class_name, Class.new(::ActiveRecord::Base)
-          )
+        class << self
+          # @param source_class_name (see CommonProvider::ModuleMethods#find_or_build_record_class)
+          #
+          # @return [ActiveRecord::Base]
+          def build_record_class(source_class_name)
+            Datamappify::Data::Record::ActiveRecord.const_set(
+              source_class_name, Class.new(::ActiveRecord::Base)
+            )
+          end
+
+          # @return [void]
+          def build_record_association(attribute, default_source_class)
+            default_source_class.class_eval <<-CODE, __FILE__, __LINE__ + 1
+              has_one :#{attribute.source_key}
+            CODE
+
+            attribute.source_class.class_eval <<-CODE, __FILE__, __LINE__ + 1
+              belongs_to :#{default_source_class.model_name.element}
+            CODE
+          end
         end
       end
     end

data/lib/datamappify/data/provider/common_provider.rb

@@ -30,6 +30,8 @@ module Datamappify
 
           # Finds or builds a data record class from the data provider
           #
+          # @param source_class_name [String]
+          #
           # @return [Class]
           #   the data record class
           def find_or_build_record_class(source_class_name)

data/lib/datamappify/data/provider/sequel.rb

@@ -4,12 +4,31 @@ module Datamappify
       module Sequel
         extend CommonProvider
 
-        # @return [Sequel::Model]
-        def self.build_record_class(source_class_name)
-          Record::Sequel.const_set(
-            source_class_name, Class.new(::Sequel::Model(source_class_name.pluralize.underscore.to_sym))
-          ).tap do |klass|
-            klass.raise_on_save_failure = true
+        class << self
+          # @param source_class_name (see CommonProvider::ModuleMethods#find_or_build_record_class)
+          #
+          # @return [Sequel::Model]
+          def build_record_class(source_class_name)
+            Record::Sequel.const_set(
+              source_class_name, Class.new(::Sequel::Model(source_class_name.pluralize.underscore.to_sym))
+            ).tap do |klass|
+              klass.raise_on_save_failure = true
+            end
+          end
+
+          # @param attribute (see Record#build_association)
+          #
+          # @param default_source_class (see Record#build_association)
+          #
+          # @return [void]
+          def build_record_association(attribute, default_source_class)
+            default_source_class.class_eval <<-CODE, __FILE__, __LINE__ + 1
+              one_to_one :#{attribute.source_key}
+            CODE
+
+            attribute.source_class.class_eval <<-CODE, __FILE__, __LINE__ + 1
+              one_to_one :#{default_source_class.table_name.to_s.singularize}
+            CODE
           end
         end
       end

data/lib/datamappify/data/record.rb

@@ -2,11 +2,24 @@ module Datamappify
   module Data
     # A convenient class for finding or building a data record
     module Record
-      # @param provider_name [String]
-      #
-      # @param source_class_name [String]
-      def self.find_or_build(provider_name, source_class_name)
-        Provider.const_get(provider_name).find_or_build_record_class(source_class_name)
+      class << self
+        # @param provider_name [String]
+        #
+        # @param source_class_name (see CommonProvider::ModuleMethods#find_or_build_record_class)
+        #
+        # @return [Object]
+        def find_or_build(provider_name, source_class_name)
+          Provider.const_get(provider_name).find_or_build_record_class(source_class_name)
+        end
+
+        # @param attribute [Attribute]
+        #
+        # @param default_source_class [Class]
+        #
+        # @return [void]
+        def build_association(attribute, default_source_class)
+          Provider.const_get(attribute.provider_name).build_record_association(attribute, default_source_class)
+        end
       end
     end
   end