remotable 0.1.2 → 0.2.0

data/README.mdown

@@ -42,7 +42,9 @@ Specify the attributes of the local model that you want to keep in sync with the
                   :id => :remote_id
     end
 
-By default Remotable assumes that the local model and remote model are joined with the connection you would express in SQL this way: `local_model INNER JOIN remote_model ON local_model.id=remote_model.id`. But it is generally impractical to join on `local_model.id`.
+### Remote Keys
+
+By default Remotable assumes that the local model and remote model are joined with the connection you might express in SQL this way: `local_model INNER JOIN remote_model ON local_model.id=remote_model.id`. But it is generally impractical to join on `local_model.id`.
 
 If you specify `attr_remote :id => :remote_id`, then the join will be on `local_model.remote_id=remote_model.id`, but you can also use a different attribute as the join key:
 
@@ -56,17 +58,39 @@ If you specify `attr_remote :id => :remote_id`, then the join will be on `local_
 
 Now, the join could be expressed this way: `local_model.slug=remote_model.slug`.
 
+If you must look up a remote model with more than one attribute, you can express a composite key this way:
+
+    class Event < ActiveRecord::Base
+      remote_model RemoteEvent
+      attr_remote :calendar_id,
+                  :id => :remote_id
+      remote_key  [:calendar_id, :remote_id]
+    end
+
 ### Finders
 
-For all of the local attributes that you've remoted (`slug`, `name`, and `remote_id` in the example above), the remoted model will respond to custom finders (e.g. `find_by_slug`, `find_by_name`, and `find_by_remote_id`). These finders will _first_ look in the local database for the requested record and, if it isn't found, look for the resource remotely. If a finder finds the resource remotely, it creates a local copy and returns that.
+For `:id` or whatever you chose to be the remote key, Remotable will create a finder method on the ActiveRecord model. These finders will _first_ look in the local database for the requested record and, if it isn't found, look for the resource remotely. If a finder finds the resource remotely, it creates a local copy and returns that.
 
-Without any further configuration, Remotable will assume the route to for the customer finder from the attribute. For example,
+You can create additional finder with the `find_by` method:
 
-    find_by_id(...)            # Looks in api_path/tenants/:id
-    find_by_slug(...)          # Looks in api_path/tenants/by_slug/:slug
-    find_by_customer_name(...) # Looks in api_path/tenants/by_customer_name/:customer_name
+    class Tenant < ActiveRecord::Base
+      remote_model RemoteTenant
+      attr_remote :slug,
+                  :customer_name => :name,
+                  :id => :remote_id
+      find_by :slug
+      find_by :name
+    end
 
-You can specify a custom path with the `find_by` method or you can always write an appropriate `find_by_whatever` method on your remote resource.
+Remotable will create the following methods and assume the URI for the custom finders from the attribute. The example above will create the following methods:
+
+    find_by_remote_id(...)    # Looks in api_path/tenants/:id
+    find_by_slug(...)         # Looks in api_path/tenants/by_slug/:slug
+    find_by_name(...)         # Looks in api_path/tenants/by_name/:name
+
+Note that the finder methods are named with the _local_ attributes.
+
+You can specify a custom path with the `find_by` method:
 
     class Tenant < ActiveRecord::Base
       remote_model RemoteTenant
@@ -76,6 +100,7 @@ You can specify a custom path with the `find_by` method or you can always write
       find_by :name, :path => "by_nombre/:name"
     end
 
+
 When you use `find_by`, give the name of the _local_ attribute not the remote one (if they differ). Also, the name of the symbolic part of the path should match the local attribute name as well.
 
 ### Expiration
@@ -91,6 +116,21 @@ Whenever a remoted record is instantiated, Remotable checks the value of its `ex
 
 Remotable checks class you hand to `remote_model` to see what it inherits from. Remotable checks this to use the correct adapter with the remote model. Currently, the only adapter included in Remotable is for ActiveResource::Base.
 
+### Custom Backends / Adapters
+
+You can write your own backends for Remotable. Just hand `remote_model` an object which responds to two methods: `new_resource` and `find_by`.
+
+ * `new_resource` should take 0 arguments and return an uninitialized object which represents a remote resource.
+ * `find_by` &mdash; either `find_by(path)` or `find_by(remote_attr, value)` &mdash; should take either 1 or 2 arguments. If it takes 1 argument, it will be passed the relative path of a remote resource. If it takes 2 arguments, it will be passed an attribute name and value to be used to look up a remote resource. `find_by` should return either a single remote resource or nil (if none could be found).
+
+The instances of a remote resource must also respond to certain methods. Instance should respond to:
+
+ * `save` (return true if successful, false if not)
+ * `destroy`
+ * `errors` (a hash of errors to be populated by an unsuccessful save)
+ * the getters and setters for all attributes which will be synchronized remotely
+
+
 ## Development
 
 ### To Do

data/lib/remotable.rb

@@ -1,5 +1,7 @@
 require "remotable/version"
 require "remotable/nosync"
+require "remotable/validate_models"
+require "remotable/with_remote_model_proxy"
 
 
 # Remotable keeps a locally-stored ActiveRecord
@@ -30,22 +32,116 @@ require "remotable/nosync"
 #
 module Remotable
   extend Nosync
+  extend ValidateModels
   
+  # By default, Remotable will validate the models you
+  # supply it via +remote_model+. You can set validate_models
+  # to false to skip this validation. It is recommended that
+  # you keep validation on in development and test environments,
+  # but turn it off in production.
+  self.validate_models = true
   
   
+  # == remote_model( model [optional] )
+  # 
+  # When called without arguments, this method returns
+  # the remote model connected to this local ActiveRecord
+  # model.
+  #
+  # When called with an argument, it extends the ActiveRecord
+  # model on which it is called.
+  #
+  # <tt>model</tt> can be a class that inherits from any
+  # of these API consumers:
+  #
+  #  * ActiveResource
+  # 
+  # <tt>model</tt> can be any object that responds
+  # to these two methods for getting a resource:
+  #
+  #  * +find_by(path)+ or +find_by(remote_attr, value)+
+  #      +find_by+ can be defined to take either one argument or two.
+  #      If it takes one argument, it will be passed path.
+  #      If it takes two, it will be passed remote_attr and value.
+  #  * +new_resource+
+  # 
+  # Resources must respond to:
+  #
+  #  * +save+ (return true on success and false on failure)
+  #  * +destroy+
+  #  * +errors+ (returning a hash of error messages by attribute)
+  #  * getters and setters for each attribute
+  #
   def remote_model(*args)
     if args.any?
       @remote_model = args.first
       
-      require "remotable/active_record_extender"
-      include Remotable::ActiveRecordExtender
+      @__remotable_included ||= begin
+        require "remotable/active_record_extender"
+        include Remotable::ActiveRecordExtender
+        true
+      end
+      
+      extend_remote_model(@remote_model)
+    end
+    @remote_model
+  end
+  
+  
+  
+  def with_remote_model(model)
+    if block_given?
+      begin
+        original = self.remote_model
+        self.remote_model(model)
+        yield
+      ensure
+        self.remote_model(original)
+      end
     else
-      @remote_model
+      WithRemoteModelProxy.new(self, model)
     end
   end
   
   
   
+  REQUIRED_CLASS_METHODS = [:find_by, :new_resource]
+  REQUIRED_INSTANCE_METHODS = [:save, :errors, :destroy]
+  
+  class InvalidRemoteModel < ArgumentError; end
+  
+  
+  
+private
+  
+  def extend_remote_model(remote_model)
+    if remote_model.is_a?(Class) and (remote_model < ActiveResource::Base)
+      require "remotable/adapters/active_resource"
+      remote_model.send(:include, Remotable::Adapters::ActiveResource)
+    
+    #
+    # Adapters for other API consumers can be implemented here
+    #
+    
+    else
+      assert_that_remote_model_meets_api_requirements!(remote_model) if Remotable.validate_models?
+    end
+  end
+  
+  def assert_that_remote_model_meets_api_requirements!(model)
+    unless model.respond_to_all?(REQUIRED_CLASS_METHODS)
+      raise InvalidRemoteModel,
+        "#{model} cannot be used as a remote model with Remotable " <<
+        "because it does not define these methods: #{model.does_not_respond_to(REQUIRED_CLASS_METHODS).join(", ")}."
+    end
+    instance = model.new_resource
+    unless instance.respond_to_all?(REQUIRED_INSTANCE_METHODS)
+      raise InvalidRemoteModel,
+        "#{instance.class} cannot be used as a remote resource with Remotable " <<
+        "because it does not define these methods: #{instance.does_not_respond_to(REQUIRED_INSTANCE_METHODS).join(", ")}."
+    end
+  end
+  
 end
 
 

data/lib/remotable/active_record_extender.rb

@@ -1,5 +1,6 @@
 require "remotable/core_ext"
 require "active_support/concern"
+require "active_support/core_ext/array/wrap"
 
 
 module Remotable
@@ -22,12 +23,9 @@ module Remotable
       
       validates_presence_of :expires_at
       
-      default_remote_attributes = column_names - %w{id created_at updated_at expires_at}
-      @remote_attribute_map = default_remote_attributes.map_to_self
-      @remote_attribute_routes = {}
-      @expires_after = 1.day
-      
-      extend_remote_model
+      @remote_attribute_map ||= default_remote_attributes.map_to_self
+      @local_attribute_routes ||= {}
+      @expires_after ||= 1.day
     end
     
     
@@ -39,24 +37,44 @@ module Remotable
         Remotable.nosync? || super
       end
       
+      # Sets the key with which a resource is identified remotely.
+      # If no remote key is set, the remote key is assumed to be :id.
+      # Which could be explicitly set like this:
+      #
+      #     remote_key :id
+      #
+      # It can can be a composite key:
+      #
+      #     remote_key [:calendar_id, :id]
+      #
+      # You can also supply a path for the remote key which will
+      # be passed to +fetch_with+:
+      #
+      #     remote_key [:calendar_id, :id], :path => "calendars/:calendar_id/events/:id"
+      #
       def remote_key(*args)
         if args.any?
-          remote_key = args.first
-          raise("#{remote_key} is not the name of a remote attribute") unless remote_attribute_names.member?(remote_key)
+          remote_key = args.shift
+          options = args.shift || {}
+          
+          # remote_key may be a composite of several attributes
+          # ensure that all of the attributs have been defined
+          Array.wrap(remote_key).each do |attribute|
+            raise(":#{attribute} is not the name of a remote attribute") unless remote_attribute_names.member?(attribute)
+          end
+          
+          # Set up a finder method for the remote_key
+          fetch_with(local_key(remote_key), options)
+          
           @remote_key = remote_key
-          fetch_with(remote_key)
-          remote_key
         else
           @remote_key || generate_default_remote_key
         end
       end
       
       def expires_after(*args)
-        if args.any?
-          @expires_after = args.first
-        else
-          @expires_after
-        end
+        @expires_after = args.first if args.any?
+        @expires_after
       end
       
       def attr_remote(*attrs)
@@ -64,23 +82,29 @@ module Remotable
         map = attrs.map_to_self.merge(map)
         @remote_attribute_map = map
         
-        @remote_attribute_routes = {}
-        fetch_with(*local_attribute_names)
+        assert_that_remote_resource_responds_to_remote_attributes!(remote_model) if Remotable.validate_models?
+        
+        # Reset routes
+        @local_attribute_routes = {}
       end
       
-      def fetch_with(*local_keys)
-        remote_keys_and_routes = extract_remote_keys_and_routes(*local_keys)
-        @remote_attribute_routes.merge!(remote_keys_and_routes)
+      def fetch_with(local_key, options={})
+        @local_attribute_routes.merge!(local_key => options[:path])
       end
       alias :find_by :fetch_with
       
       
       
       attr_reader :remote_attribute_map,
-                  :remote_attribute_routes
+                  :local_attribute_routes
       
-      def local_key
-        local_attribute_name(remote_key)
+      def local_key(remote_key=nil)
+        remote_key ||= self.remote_key
+        if remote_key.is_a?(Array)
+          remote_key.map(&method(:local_attribute_name))
+        else
+          local_attribute_name(remote_key)
+        end
       end
       
       def remote_attribute_names
@@ -99,17 +123,18 @@ module Remotable
         remote_attribute_map[remote_attr] || remote_attr
       end
       
-      def route_for(local_key)
-        remote_key = remote_attribute_name(local_key)
-        remote_attribute_routes[remote_key] || default_route_for(local_key, remote_key)
+      def route_for(remote_key)
+        local_key = self.local_key(remote_key)
+        local_attribute_routes[local_key] || default_route_for(local_key, remote_key)
       end
       
       def default_route_for(local_key, remote_key=nil)
+        puts "local_key: #{local_key}; remote_key: #{remote_key}"
         remote_key ||= remote_attribute_name(local_key)
         if remote_key.to_s == primary_key
           ":#{local_key}"
         else
-          "by_#{remote_key}/:#{local_key}"
+          "by_#{local_key}/:#{local_key}"
         end
       end
       
@@ -128,26 +153,55 @@ module Remotable
       
       
       
+      def respond_to?(method_sym, include_private=false)
+        return true if recognize_remote_finder_method(method_sym)
+        super(method_sym, include_private)
+      end
+      
       def method_missing(method_sym, *args, &block)
-        method_name = method_sym.to_s
-        
-        if method_name =~ /find_by_([^!]*)(!?)/
-          local_attr, bang, value = $1.to_sym, !$2.blank?, args.first
-          remote_attr = remote_attribute_name(local_attr)
-          
-          remote_key # Make sure we've figured out the remote
-                     # primary key if we're evaluating a finder
+        method_details = recognize_remote_finder_method(method_sym)
+        if method_details
+          local_attributes = method_details[:local_attributes]
+          values = args
           
-          if remote_attribute_routes.key?(remote_attr)
-            local_resource = where(local_attr => value).first ||
-                             fetch_by(remote_attr, value)
-            
-            raise ActiveRecord::RecordNotFound if local_resource.nil? && bang
-            return local_resource
+          unless values.length == local_attributes.length
+            raise ArgumentError, "#{method_sym} was called with #{values.length} but #{local_attributes.length} was expected"
           end
+          
+          local_resource = ((0...local_attributes.length).inject(scoped) do |scope, i|
+            scope.where(local_attributes[i] => values[i])
+          end).first || fetch_by(method_details[:remote_key], *values)
+          
+          raise ActiveRecord::RecordNotFound if local_resource.nil? && (method_sym =~ /!$/)
+          local_resource
+        else
+          super(method_sym, *args, &block)
+        end
+      end
+      
+      # If the missing method IS a Remotable finder method,
+      # returns the remote key (may be a composite key).
+      # Otherwise, returns false.
+      def recognize_remote_finder_method(method_sym)
+        method_name = method_sym.to_s
+        return false unless method_name =~ /find_by_([^!]*)(!?)/
+        
+        local_attributes = $1.split("_and_").map(&:to_sym)
+        remote_attributes = local_attributes.map(&method(:remote_attribute_name))
+        
+        local_key, remote_key = if local_attributes.length == 1
+          [local_attributes[0], remote_attributes[0]]
+        else
+          [local_attributes, remote_attributes]
         end
         
-        super(method_sym, *args, &block)
+        generate_default_remote_key # <- Make sure we've figured out the remote
+                                    #    primary key if we're evaluating a finder
+        
+        return false unless local_attribute_routes.key?(local_key)
+        
+        { :local_attributes => local_attributes,
+          :remote_key => remote_key }
       end
       
       
@@ -161,56 +215,90 @@ module Remotable
       # Looks the resource up remotely, by the given attribute
       # If the resource is found, wraps it in a new local resource
       # and returns that.
-      def fetch_by(remote_attr, value)
-        remote_resource = remote_model.find_by(remote_attr, value)
+      def fetch_by(remote_attr, *values)
+        remote_resource = find_remote_resource_by(remote_attr, *values)
         remote_resource && new_from_remote(remote_resource)
       end
       
+      # Looks the resource up remotely;
+      # Returns the remote resource.
+      def find_remote_resource_by(remote_attr, *values)
+        find_by = remote_model.method(:find_by)
+        case find_by.arity
+        when 1; find_by.call(remote_path_for(remote_attr, *values))
+        when 2; find_by.call(remote_attr, *values)
+        else
+          raise InvalidRemoteModel, "#{remote_model}.find_by should take either 1 or 2 parameters"
+        end
+      end
+      
+      def remote_path_for(remote_key, *values)
+        route = route_for(remote_key)
+        local_key = self.local_key(remote_key)
+        
+        if remote_key.is_a?(Array)
+          remote_path_for_composite_key(route, local_key, values)
+        else
+          remote_path_for_simple_key(route, local_key, values.first)
+        end
+      end
+      
+      def remote_path_for_simple_key(route, local_key, value)
+        route.gsub(/:#{local_key}/, value.to_s)
+      end
+      
+      def remote_path_for_composite_key(route, local_key, values)
+        unless values.length == local_key.length
+          raise ArgumentError, "local_key has #{local_key.length} attributes but values has #{values.length}"
+        end
+        
+        (0...values.length).inject(route) do |route, i|
+          route.gsub(/:#{local_key[i]}/, values[i].to_s)
+        end
+      end
+      
       
       
     private
       
       
       
-      def extend_remote_model
-        if remote_model < ActiveResource::Base
-          require "remotable/adapters/active_resource"
-          remote_model.send(:include, Remotable::Adapters::ActiveResource)
-          remote_model.local_model = self
-        
-        # !todo
-        # Adapters for other API consumers can be implemented here
-        #
-        
-        else
-          raise("#{remote_model} is not a recognized remote resource")
-        end
+      def default_remote_attributes
+        column_names - %w{id created_at updated_at expires_at}
       end
       
       
-      def extract_remote_keys_and_routes(*local_keys)
-        keys_and_routes = local_keys.extract_options!
-        {}.tap do |hash|
-          local_keys.each {|local_key| hash[remote_attribute_name(local_key)] = nil}
-          keys_and_routes.each {|local_key, value| hash[remote_attribute_name(local_key)] = value}
+      
+      def assert_that_remote_resource_responds_to_remote_attributes!(model)
+        # Skip this for ActiveResource because it won't define a method until it has
+        # loaded an JSON for that method
+        return if model.is_a?(Class) and (model < ActiveResource::Base) 
+        
+        instance = model.new_resource
+        attr_getters_and_setters = remote_attribute_names + remote_attribute_names.map {|attr| :"#{attr}="}
+        unless instance.respond_to_all?(attr_getters_and_setters)
+          raise InvalidRemoteModel,
+            "#{instance.class} does not respond to getters and setters " <<
+            "for each remote attribute (not implemented: #{instance.does_not_respond_to(attr_getters_and_setters).sort.join(", ")}).\n"
         end
       end
       
       
+      
       def generate_default_remote_key
+        return @remote_key if @remote_key
         raise("No remote key supplied and :id is not a remote attribute") unless remote_attribute_names.member?(:id)
         remote_key(:id)
       end
       
       
+      
       def new_from_remote(remote_resource)
         record = self.new
         record.instance_variable_set(:@remote_resource, remote_resource)
         record.pull_remote_data!
       end
       
-      
-      
     end
     
     
@@ -224,6 +312,7 @@ module Remotable
              :local_attribute_names,
              :local_attribute_name,
              :expires_after,
+             :find_remote_resource_by,
              :to => "self.class"
     
     def expired?
@@ -256,7 +345,10 @@ module Remotable
     
     def fetch_remote_resource
       fetch_value = self[local_key]
-      remote_model.find_by(remote_key, fetch_value)
+      # puts "local_key", local_key.inspect, "",
+      #      "remote_key", remote_key.inspect, "",
+      #      "fetch_value", fetch_value
+      find_remote_resource_by(remote_key, fetch_value)
     end
     
     def merge_remote_data!(remote_resource)
@@ -285,7 +377,7 @@ module Remotable
     end
     
     def create_remote_resource
-      @remote_resource = remote_model.new
+      @remote_resource = remote_model.new_resource
       merge_local_data(@remote_resource)
       
       if @remote_resource.save
@@ -323,8 +415,10 @@ module Remotable
     
     
     def merge_remote_errors(errors)
-      errors.each do |attribute, message|
-        self.errors[local_attribute_name(attribute)] = message
+      errors.each do |attribute, messages|
+        Array.wrap(messages).each do |message|
+          self.errors.add(local_attribute_name(attribute), message)
+        end
       end
       self
     end