restforce-db 0.5.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 530452ffeea884be628f06f4227de2fe1404ebc4
-  data.tar.gz: 2b94172a1c712955af08ac61f3131a1de4d3ea83
+  metadata.gz: b090d0384c8a485ace8705c39d9247d02a7b6c98
+  data.tar.gz: 835e23b61f087b6ef9d66baf0a927f19d285e6d6
 SHA512:
-  metadata.gz: 6cb953ba90c351994aeccef4fd2ffefefe5364955fa6c566098166f5053d74f121a4d2cc69629bba386c96b932d7a7c8ad657dcc609c359cbb50c75b4cd3aa08
-  data.tar.gz: d1e69dfef74e097947fcbe5abfaa31aa2d6b73e74e373ae2ad9605db9c0445ed26717c1b8531cec1e624b27adc1bcc3a13dea3ab25da40448be1199495a45548
+  metadata.gz: 05a85db585c7e7fe76c637dec68332123b1bf195c3ddde90747b33a3d202ce83a6e4ec0e9317bc81a6a2f80655cd62e85c7fb6882d442d0d89373187ec6c7a1a
+  data.tar.gz: d6a81ca6fece5297c1ce7b8e115f0fd04f24fef6110537bbed27a9b873f97694cd817475d6ec076f523696063694f891f9f6742412909a67c40e8abb79cd73e5

data/README.md

@@ -41,16 +41,14 @@ class Restaurant < ActiveRecord::Base
   include Restforce::DB::Model
   has_one :specialty, class_name: "Dish"
 
-  sync_with(
-    "Restaurants__c",
-    fields: {
+  sync_with("Restaurant__c", :always) do
+    where "StarRating__c > 4"
+    belongs_to :specialty, through: %w(Specialty__c KeyIngredient__c)
+    maps(
       name:  "Name",
       style: "Style__c",
-    },
-    associations: {
-      specialty: "Specialty__c",
-    },
-  )
+    )
+  end
 
 end
 
@@ -59,24 +57,82 @@ class Dish < ActiveRecord::Base
   include Restforce::DB::Model
   belongs_to :restaurant
 
-  sync_with(
-    "Dish__c",
-    through: "Specialty__c",
-    fields: {
-      name:       "Name",
-      ingredient: "Ingredient__c",
-    },
-  )
+  sync_with("Dish__c", :passive) do
+    has_one :restaurant, through: "Specialty__c"
+    maps(
+      name:   "Name",
+      origin: "Origin__c",
+    )
+  end
+
+  sync_with("Ingredient__c", :passive) do
+    has_one :restaurant, through: "KeyIngredient__c"
+    maps(
+      key_ingredient: "Name",
+    )
+  end
+
 end
 ```
 
 This will automatically register the models with entries in the `Restforce::DB::Mapping` collection. This collection defines the manner in which the database and Salesforce systems will be synchronized.
 
-There are a few options to be aware of when describing a mapping:
+Demonstrated above, `Restforce::DB` has its own DSL for defining mappings, heavily inspired by the ActiveRecord model DSL. The various options are outlined here.
+
+#### Synchronization Strategies
+
+The second argument to `sync_with` is a Symbol, reflecting the desired synchronization strategy for the mapping. Valid options are as follows:
+
+##### `:always`
+
+An `always` synchronization strategy will create any new records it encounters while polling for changes, and once the object has been persisted in both systems, will update that object any time changes are made to the matching object in the other system.
+
+Associations defined on an `always` mapping will trigger the creation of those associated records on initial record creation.
+
+##### `:passive`
+
+A `passive` synchronization strategy will update all modified records that already exist in both systems, but will not directly create any new records. Objects defined with a `passive` mapping can only be created as a by-product of another mapping's association definitions (via an `always` strategy).
+
+##### `:associated`
+
+_Coming Soon_
+
+#### Lookup Conditions
+
+`where` accepts one or more query strings which will be used to filter _all_ queries performed for the specific mapping. In the example above, Restaurant objects will only be detected in Salesforce if they exceed a certain value for the `StarRating__c` field.
+
+Individual conditions supplied to `where` will be appended together with `AND` clauses, and must be composed of valid [`SOQL`](http://www.salesforce.com/us/developer/docs/soql_sosl/).
+
+#### Field Mappings
+
+`maps` defines a set of direct field-to-field mappings. It takes a Hash as an argument; the keys should line up with your ActiveRecord attribute names, while the values should line up with the matching field names in Salesforce.
+
+#### Associations
+
+Associations in `Restforce::DB` can be a little tricky, as they depend on your ActiveRecord association mappings, but are independent of those mappings, and can even (as seen above) seem to conflict with them.
+
+If your Salesforce objects have parity with your ActiveRecord models, your association mappings will likely have parity, as well. But, as demonstrated above, you should define your association mappings based on your Salesforce schema.
+
+##### `belongs_to`
+
+This defines an association type in which the Lookup (i.e., foreign key) _is on the mapped Salesforce model_. In the example above, the `Restaurant__c` object type in Salesforce has two Lookup fields:
+
+- `Specialty__c`, which corresponds to the `Dish__c` object type, and
+- `KeyIngredient__c`, which corresponds to the `Ingredient__c` object type
+ 
+Thus, the `Restaurant__c` mapping declares a `belongs_to` relationship to `:specialty`, with a `:through` argument referencing both of the Lookups used by the mappings on the associated `Dish` class.
+
+As shown above, the `:through` option may contain _an array of Lookup field names_, which may be useful if more than one mapping on the associated ActiveRecord model refers to a Lookup on the same Salesforce record.
+
+##### `has_one`
+
+This defines an inverse relationship for a `belongs_to` relationship. In the example above, `Dish` defines _two_ `has_one` relationships with `:restaurant`, one for each mapping. The `:through` arguments for each call to `has_one` correspond to the relevant Lookup field on the parent object.
+
+In the above example, given the relationships defined between our records, we can ascertain that `Restaurant__c.Specialty__c` is a `Lookup(Dish__c)` field in Salesforce, while ` Restaurant__c.KeyIngredient__c` is a `Lookup(Ingredient__c)`.
+
+##### `has_many`
 
-- `fields`: These are direct field-to-field mappings. The keys should line up with your ActiveRecord attribute names, while the values should line up with the matching field names in Salesforce.
-- `associations`: These are mappings of ActiveRecord associations to Salesforce lookups. Associations defined here will be built as part of the creation process for a newly-synced record. 
-- `through`: This should be set for models which are created through an association. It references the lookup field on its parent's Salesforce object type.
+_Coming Soon_
 
 ### Run the daemon
 
@@ -100,7 +156,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Caveats
 
-- **Update Prioritization.** When synchronization occurs, newly-updated records in Salesforce are prioritized over newly-updated database records. This means that any changes to records in the database may be overwritten if changes were made to the Salesforce at the same time.
+- **Update Prioritization.** When synchronization occurs, the most recently updated record, Salesforce or database, gets to make the final call about the values of _all_ of the fields it observes. This means that race conditions can and probably will happen if both systems are updated within the same polling interval.
 - **API Usage.** This gem performs most of its functionality via the Salesforce API (by way of the [`restforce`](https://github.com/ejholmes/restforce) gem). If you're at risk of hitting your Salesforce API limits, this may not be the right approach for you.
 
 ## Contributing

data/lib/restforce/db.rb

@@ -5,6 +5,9 @@ require "restforce/extensions"
 
 require "restforce/db/version"
 require "restforce/db/configuration"
+require "restforce/db/registry"
+require "restforce/db/strategy"
+require "restforce/db/dsl"
 
 require "restforce/db/associations/active_record"
 
@@ -16,6 +19,9 @@ require "restforce/db/record_types/base"
 require "restforce/db/record_types/active_record"
 require "restforce/db/record_types/salesforce"
 
+require "restforce/db/strategies/always"
+require "restforce/db/strategies/passive"
+
 require "restforce/db/runner"
 
 require "restforce/db/accumulator"

data/lib/restforce/db/associations/active_record.rb

@@ -28,7 +28,7 @@ module Restforce
         #
         # Returns the constructed associated record.
         def build(from_record)
-          Mapping[associated.class].each do |mapping|
+          Registry[associated.class].each do |mapping|
             lookup_id = from_record[mapping.through]
             apply(mapping, lookup_id)
           end

data/lib/restforce/db/attribute_map.rb

@@ -59,7 +59,11 @@ module Restforce
       #
       # Examples
       #
-      #   mapping = Mapping.new(MyClass, "Object__c", some_key: "SomeField__c")
+      #   mapping = AttributeMap.new(
+      #     MyClass,
+      #     "Object__c",
+      #     some_key: "SomeField__c",
+      #   )
       #
       #   mapping.convert("Object__c", some_key: "some value")
       #   # => { "Some_Field__c" => "some value" }

data/lib/restforce/db/dsl.rb

@@ -0,0 +1,80 @@
+module Restforce
+
+  module DB
+
+    # Restforce::DB::DSL defines a syntax through which a Mapping may be
+    # configured between a database model and an object type in Salesforce.
+    class DSL
+
+      attr_reader :mapping
+
+      # Public: Initialize a Restforce::DB::DSL.
+      #
+      # database_model   - An ActiveRecord::Base subclass.
+      # salesforce_model - A String Salesforce object name.
+      # strategy_name    - A Symbol initialization strategy name.
+      # options          - A Hash of options to pass to the Strategy object.
+      #
+      # Returns nothing.
+      def initialize(database_model, salesforce_model, strategy_name, options = {})
+        strategy = Strategy.for(strategy_name, options)
+        @mapping = Mapping.new(database_model, salesforce_model, strategy)
+        Registry << @mapping
+      end
+
+      # Public: Define a set of conditions which should be used to filter the
+      # Salesforce record lookups for this mapping.
+      #
+      # conditions - An Array of String query conditions.
+      #
+      # Returns nothing.
+      def where(*conditions)
+        @mapping.conditions = conditions
+      end
+
+      # Public: Define a relationship in which the current mapping contains the
+      # lookup ID for another mapping.
+      #
+      # TODO: This should eventually be implemented as a full-fledged
+      # association on the mapping. Something like:
+      # @mapping.associate(association, Associations::BelongsTo, options)
+      #
+      # association - The name of the ActiveRecord association.
+      # options     - A Hash of options to pass to the association.
+      #
+      # Returns nothing.
+      def belongs_to(association, options)
+        @mapping.associations[association] = options[:through]
+      end
+
+      # Public: Define a relationship in which the current mapping is referenced
+      # by one object through a lookup ID on another mapping.
+      #
+      # TODO: This should eventually be implemented as a full-fledged
+      # association on the mapping. Something like:
+      # @mapping.associate(association, Associations::HasOne, options)
+      #
+      # association - The name of the ActiveRecord association.
+      # options     - A Hash of options to pass to the association.
+      #
+      # Returns nothing.
+      def has_one(_association, options) # rubocop:disable PredicateName
+        @mapping.through = options[:through]
+      end
+
+      # Public: Define a set of fields which should be synchronized between the
+      # database record and Salesforce.
+      #
+      # fields - A Hash, with keys corresponding to attributes of the database
+      #          record, and values corresponding to field names in Salesforce.
+      #
+      # Returns nothing.
+      def maps(fields)
+        @mapping.fields = fields
+      end
+
+    end
+
+  end
+
+end

data/lib/restforce/db/initializer.rb

@@ -14,6 +14,7 @@ module Restforce
       # runner  - A Restforce::DB::Runner.
       def initialize(mapping, runner = Runner.new)
         @mapping = mapping
+        @strategy = mapping.strategy
         @runner = runner
       end
 
@@ -21,7 +22,7 @@ module Restforce
       #
       # Returns nothing.
       def run
-        return unless @mapping.root?
+        return if @strategy.passive?
 
         @runner.run(@mapping) do |run|
           run.salesforce_records { |record| create_in_database(record) }
@@ -39,7 +40,7 @@ module Restforce
       #
       # Returns nothing.
       def create_in_database(record)
-        return if record.synced?
+        return unless @strategy.build?(record)
         @mapping.database_record_type.create!(record)
       end
 

data/lib/restforce/db/mapping.rb

@@ -9,57 +9,9 @@ module Restforce
 
       class InvalidMappingError < StandardError; end
 
-      class << self
-
-        include Enumerable
-        attr_accessor :collection
-
-        # Public: Get the Restforce::DB::Mapping entry for the specified model.
-        #
-        # model - A String or Class.
-        #
-        # Returns a Restforce::DB::Mapping.
-        def [](model)
-          collection[model]
-        end
-
-        # Public: Iterate through all registered Restforce::DB::Mappings.
-        #
-        # Yields one Mapping for each database-to-Salesforce mapping.
-        # Returns nothing.
-        def each
-          collection.each do |model, mappings|
-            # Since each mapping is inserted twice, we ignore the half which
-            # were inserted via Salesforce model names.
-            next unless model.is_a?(Class)
-
-            mappings.each do |mapping|
-              yield mapping
-            end
-          end
-        end
-
-        # Public: Add a mapping to the overarching Mapping collection. Appends
-        # the mapping to the collection for both its database and salesforce
-        # object types.
-        #
-        # mapping - A Restforce::DB::Mapping.
-        #
-        # Returns nothing.
-        def <<(mapping)
-          [mapping.database_model, mapping.salesforce_model].each do |model|
-            collection[model] ||= []
-            collection[model] << mapping
-          end
-        end
-
-      end
-
-      self.collection ||= {}
-
       extend Forwardable
       def_delegators(
-        :@attribute_map,
+        :attribute_map,
         :attributes,
         :convert,
         :convert_from_salesforce,
@@ -70,42 +22,32 @@ module Restforce
         :salesforce_model,
         :database_record_type,
         :salesforce_record_type,
+      )
+
+      attr_accessor(
+        :fields,
         :associations,
         :conditions,
         :through,
+        :strategy,
       )
 
       # Public: Initialize a new Restforce::DB::Mapping.
       #
       # database_model   - A Class compatible with ActiveRecord::Base.
       # salesforce_model - A String name of an object type in Salesforce.
-      # options          - A Hash of mapping attributes. Currently supported
-      #                    keys are:
-      #                    :fields       - A Hash of mappings between database
-      #                                    columns and fields in Salesforce.
-      #                    :associations - A Hash of mappings between Active
-      #                                    Record association names and the
-      #                                    corresponding Salesforce Lookup name.
-      #                    :conditions   - An Array of lookup conditions which
-      #                                    should be applied to the Salesforce
-      #                                    queries.
-      #                    :root         - A Boolean reflecting whether or not
-      #                                    this is a root-level mapping.
-      def initialize(database_model, salesforce_model, options = {})
+      # strategy         - A synchronization Strategy object.
+      def initialize(database_model, salesforce_model, strategy = Strategies::Always.new)
         @database_model = database_model
         @salesforce_model = salesforce_model
 
         @database_record_type = RecordTypes::ActiveRecord.new(database_model, self)
         @salesforce_record_type = RecordTypes::Salesforce.new(salesforce_model, self)
 
-        @fields = options.fetch(:fields) { {} }
-        @associations = options.fetch(:associations) { {} }
-        @conditions = options.fetch(:conditions) { [] }
-        @through = options.fetch(:through) { nil }
-
-        @attribute_map = AttributeMap.new(database_model, salesforce_model, @fields)
-
-        self.class << self
+        self.associations = {}
+        self.fields = {}
+        self.conditions = []
+        self.strategy = strategy
       end
 
       # Public: Get a list of the relevant Salesforce field names for this
@@ -113,7 +55,7 @@ module Restforce
       #
       # Returns an Array.
       def salesforce_fields
-        @fields.values + @associations.values.flatten
+        fields.values + associations.values.flatten
       end
 
       # Public: Get a list of the relevant database column names for this
@@ -121,7 +63,7 @@ module Restforce
       #
       # Returns an Array.
       def database_fields
-        @fields.keys
+        fields.keys
       end
 
       # Public: Get the name of the database column which should be used to
@@ -144,12 +86,13 @@ module Restforce
         end
       end
 
-      # Public: Is this a root-level mapping? Used to determine whether or not
-      # to trigger the creation of "missing" database records.
+      private
+
+      # Internal: Get an AttributeMap for the fields defined for this mapping.
       #
-      # Returns a Boolean.
-      def root?
-        @through.nil?
+      # Returns a Restforce::DB::AttributeMap.
+      def attribute_map
+        @attribute_map ||= AttributeMap.new(database_model, salesforce_model, fields)
       end
 
     end

data/lib/restforce/db/model.rb

@@ -16,14 +16,17 @@ module Restforce
       module ClassMethods
 
         # Public: Initializes a Restforce::DB::Mapping defining this model's
-        # relationship to a Salesforce object type.
+        # relationship to a Salesforce object type. Passes a provided block to
+        # the Restforce::DB::DSL for evaluation.
         #
         # salesforce_model - A String name of an object type in Salesforce.
+        # strategy         - A Symbol naming a desired initialization strategy.
         # options          - A Hash of options to pass through to the Mapping.
+        # block            - A block of code to evaluate through the DSL.
         #
-        # Returns a Restforce::DB::Mapping.
-        def sync_with(salesforce_model, **options)
-          Mapping.new(self, salesforce_model, options)
+        # Returns nothing.
+        def sync_with(salesforce_model, strategy = :always, options = {}, &block)
+          Restforce::DB::DSL.new(self, salesforce_model, strategy, options).instance_eval(&block)
         end
 
       end