HasRemote 0.1.0

data/.gitignore

@@ -0,0 +1,3 @@
+*.log
+/doc
+/rdoc

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009-2010 Innovation Factory, Amsterdam
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,135 @@
+= HasRemote
+
+Gives your local ActiveRecord model an ActiveResource equivalent,
+which enables you to look for certain attributes remotely using a RESTful webservice.
+
+=== Installation
+
+ script/plugins install git://github.com/innovationfactory/has_remote.git
+
+Only if you require synchronization:
+
+ script/generate has_remote_migration
+
+ rake db:migrate
+
+=== Examples
+
+First make sure your records have a reference to a remote resource:
+  add_column :users, :remote_id, :integer
+
+The default key is 'remote_id', but this can be changed, see options for has_remote.
+
+ class User < ActiveRecord::Base
+   has_remote :site => 'http://people.local'
+ end
+
+ User.remote_class
+ # => User::Remote (subclass of ActiveResource::Base)
+
+ @user.remote
+ # => #<User::Remote:...>
+
+ @user.remote.username
+ # => "User name from remote server"
+
+has_remote optionally takes a block which can be used to specify remote attributes:
+
+ class User < ActiveRecord::Base
+   has_remote :site => '...' do |remote|
+     remote.attribute :username
+   end
+ end
+
+ @user.username
+ # => "User name from remote server"
+
+Note that the current version of HasRemote only offers read-only support for remote attributes.
+
+The <tt>:through</tt> option enables you to specify your own ActiveResource class:
+
+ class RemoteUser < ActiveResource::Base
+   self.site = "people.local"
+   self.element_name = "person"
+ end
+
+ class User < ActiveRecord::Base
+   has_remote :through => "RemoteUser"
+ end
+
+See documentation for has_remote for a description of all options.
+
+=== Caching attributes locally
+
+In case certain attributes are used a lot and performance is getting bad, or in case you need to do database operations on remote attributes, like sorting, you can tell has_remote
+to locally cache specific attributes in the following manner:
+
+ class User < ActiveRecord::Base
+   has_remote :site => '...' do |remote|
+     remote.attribute :username, :local_cache => true
+     remote.attribute :email_address, :as => :email, :local_cache => true
+   end
+ end
+
+This assumes you also have a 'username' and 'email' column in the local 'users' table. Note that when using the
+<tt>:as</tt> option the local column is assumed to be named after this value.
+
+=== Synchronization of cached attributes
+
+There are two ways of keeping the locally cached attributes in sync with their remote values.
+
+1. Inline synchronization
+2. Rake task <tt>hr:sync</tt>
+
+==== Inline synchronization
+
+Synchronize a single record's attributes:
+ @user.update_cached_attributes
+
+*Tip!* It is often useful to trigger this method by means of a callback in order to initialize remote attributes when the record is created:
+ before_create :update_cached_attributes
+
+Appending an exclamation mark will also save the record:
+ @user.update_cached_attributes!
+
+Synchronize all records of one specific model:
+ User.synchronize!
+
+The latter automatically requests all remote resources that have been changed (including new and deleted records) since the last successful synchronization for this particular model.
+You may need to override the <tt>changed_remotes_since</tt> class method in your model to match your host's REST API.
+
+See <tt>HasRemote::Synchronizable</tt> for more information.
+
+==== Rake hr:sync
+
+The rake task <tt>hr:sync</tt> is provided to allow easy synchronization from the command line.
+You could set up a cron tab that runs this task regularly to keep the data in sync.
+
+By default <tt>hr:sync</tt> updates all records of each model that has remotes. You can limit this to
+certain models by using the <tt>MODELS</tt> variable:
+
+ rake hr:sync MODELS=Contact,Company
+
+=== Documentation
+
+To generate RDocs for this plugin, from the has_remote directory run:
+ rake rdoc
+or from your application's root directory, run:
+ rake doc:plugins:has_remote
+
+=== Testing
+
+To run the specs of the plugin, from the has_remote directory run:
+ rake spec
+
+(This requires you to have both RSpec and Shoulda installed.)
+
+=== More information & patches
+
+- Simple example of how HasRemote simplifies your code: http://gist.github.com/176335
+- Simple API authentication with HasRemote: http://gist.github.com/174497
+
+Questions, requests and patches can be directed to sjoerd.andringa[AT]innovationfactory[DOT]nl.
+
+
+Copyright (c) 2009 Innovation Factory.

data/Rakefile

@@ -0,0 +1,35 @@
+require 'rubygems'
+require 'rake'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+
+desc 'Generate documentation for the has_remote plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = 'HasRemote'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_files.exclude('lib/generators')
+end
+
+desc "Run all RSpec examples"
+Spec::Rake::SpecTask.new('spec') do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.spec_opts = %w(-cfs)
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name        = "HasRemote"
+    gemspec.summary     = "Bind a remote ActiveResource object to your local ActiveRecord objects."
+    gemspec.description = "Bind a remote ActiveResource object to your local ActiveRecord objects, delegate attributes and optionally cache remote attributes locally."
+    gemspec.email       = "sjoerd.andringa@innovationfactory.eu"
+    gemspec.homepage    = "http://github.com/innovationfactory/has_remote"
+    gemspec.authors     = ["Sjoerd Andringa"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end

data/TODO

@@ -0,0 +1,21 @@
+= Todos and ideas
+
+ - Creating, updating and destroying resources both locally and remote transparently.
+ - Allow for multiple remotes, so that composing one object from different resources becomes a possibility.
+ - Make <tt>to_xml</tt> and <tt>to_json</tt> etc. optionally merge in remote attributes (<tt>to_xml(:remotes => :merge)</tt>).
+
+ <user>
+   <id type="integer">1</id>
+   <remote_id type="integer">1</remote_id>
+   <name>George Remote</name>
+ </user>
+
+ - Make <tt>to_xml</tt> etc. optionally include remotes, so consumers may talk to origins directly (<tt>to_xml(:remotes => :include)</tt>).
+
+ <user>
+   <id type="integer">1</id>
+   <remote site="...">
+	   <id type="integer">1</id>
+	   <name>George Remote</name>
+	 </remote>
+ </user>

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/init.rb

@@ -0,0 +1 @@
+ActiveRecord::Base.send(:include, HasRemote)

data/lib/generators/has_remote_migration/has_remote_migration_generator.rb

@@ -0,0 +1,7 @@
+class HasRemoteMigrationGenerator < Rails::Generator::Base #:nodoc:
+  def manifest
+    record do |m|
+      m.migration_template "create_has_remote_synchronizations.erb", File.join("db", "migrate"), :migration_file_name => 'create_has_remote_synchronizations'
+    end
+  end
+end

data/lib/generators/has_remote_migration/templates/create_has_remote_synchronizations.erb

@@ -0,0 +1,13 @@
+class CreateHasRemoteSynchronizations < ActiveRecord::Migration
+  def self.up
+    create_table :has_remote_synchronizations do |t|
+      t.string :model_name, :null => false
+      t.datetime :latest_change, :null => false
+      t.datetime :created_at
+    end
+  end
+
+  def self.down
+    drop_table :has_remote_synchronizations
+  end
+end

data/lib/has_remote/synchronizable.rb

@@ -0,0 +1,144 @@
+module HasRemote
+  
+  # Contains class methods regarding synchronization of changed, added and deleted remotes.
+  #
+  # === Synchronization examples
+  #
+  # Update all cached attributes, destroy deleted records and add new records for all models that have a remote:
+  #  HasRemote.synchronize!
+  #
+  # For users only:
+  #  User.synchronize!
+  #
+  # You can also update a single record's cached attributes:
+  #  @user.update_cached_attributes
+  #
+  # Or with also saving the record:
+  #  @user.update_cached_attributes!
+  #
+  # You can make your application call these methods whenever you need to be sure
+  # your cache is up to date or use the 'hr:sync' rake task to synchronize all models
+  # from the command line.
+  #
+  # *Note* 
+  # All remote resources need to have an 'updated_at' field in order for synchronization to work. Records will 
+  # be destroyed if their remote resource's 'deleted_at' time lies before the time of synchronization.
+  #
+  module Synchronizable
+
+    # Returns an array of all attributes that are locally cached.
+    #
+    def cached_attributes
+      @cached_attributes ||= []
+    end
+    
+    # Returns all remote objects that have been changed since the given time or one week ago if no
+    # time is given. This may include new and optionally deleted (tagged by a 'deleted_at' attribute) resources.
+    #
+    # This is used by the <tt>synchronize!</tt> class method. By default
+    # it queries '/updated?since=<time>' on your resources URL, where 'time' is
+    # the latest updated_at time of the last processed remote objects.
+    #
+    # You may need to override this method in your model to match your host's REST API or to change
+    # the default time, e.g.:
+    #
+    #  def self.changed_remotes_since(time = nil)
+    #    time ||= 12.hours.ago
+    #    User::Remote.find :all, :from => :search, :params => {:updated_since => time.strftime('...') }
+    #  end
+    #
+    def changed_remotes_since(time = nil)
+      time ||= 1.week.ago 
+      remote_class.find :all, :from => :updated, :params => {:since => time.to_s}  
+    end
+    
+    # Will update all records that have been created, updated or deleted on the remote host
+    # since the last successful synchronization.
+    #
+    def synchronize!(options = {})
+      logger.info( "*** Start synchronizing #{table_name} at #{Time.now.to_s :long} ***\n" )
+      @sync_count = 0
+      begin
+        changed_objects = changed_remotes_since( options[:since] || synchronized_at )
+        if changed_objects.any?
+          # Do everything within transaction to prevent ending up in half-synchronized situation if an exception is raised.
+          transaction { sync_all_records_for(changed_objects) }
+        else
+          logger.info( " - No #{table_name} to update.\n" )
+        end
+      rescue => e
+        logger.warn( " - Synchronization of #{table_name} failed: #{e} \n #{e.backtrace}" )
+      else
+        self.synchronized_at = changed_objects.map { |o| time_of_update(o) }.sort.last if changed_objects.any?  
+        logger.info( " - Synchronized #{@sync_count} #{table_name}.\n" ) if @sync_count > 0
+      ensure
+        logger.info( "*** Stopped synchronizing #{table_name} at #{Time.now.to_s :long} ***\n" )
+      end
+    end
+    
+    # Time of the last successful synchronization.
+    #
+    def synchronized_at
+      HasRemote::Synchronization.for(self.name).latest_change
+    end
+    
+  private
+
+    def synchronized_at=(time) #:nodoc:
+      HasRemote::Synchronization.create!(:model_name => self.name, :latest_change => time)
+    end
+
+    def sync_all_records_for(resources) #:nodoc:
+      resources.each { |resource| sync_all_records_for_resource(resource) }
+    end
+    
+    def sync_all_records_for_resource(resource) #:nodoc:
+      records = find(:all, :conditions => ["#{remote_foreign_key} = ?", resource.send(remote_primary_key)])
+      if records.empty?
+        create_record_for_resource(resource) unless deleted?(resource)
+      else
+        records.each { |record| sync_record_for_resource(record, resource) }
+      end
+    end
+    
+    def sync_record_for_resource(record, resource) #:nodoc:
+      if deleted?(resource)
+        delete_record_for_resource(record, resource)
+      else
+        update_and_save_record_for_resource(record, resource)
+      end
+    end
+    
+    def update_and_save_record_for_resource(record, resource) #:nodoc:
+      was_it_new = record.new_record?
+      cached_attributes.each do |remote_attr|
+        local_attr = remote_attribute_aliases[remote_attr] || remote_attr
+        record.send :write_attribute, local_attr, resource.send(remote_attr)
+      end
+      record.skip_update_cache = true # Dont update cache again on save:
+      if record.save!
+        @sync_count += 1
+        logger.info( was_it_new ? " - Created #{name.downcase} with id #{record.id}.\n" : " - Updated #{name.downcase} with id #{record.id}.\n" )
+      end
+    end
+    
+    def delete_record_for_resource(record, resource) #:nodoc:
+      record.destroy
+      @sync_count += 1
+      logger.info( " - Deleted #{name.downcase} with id #{record.id}.\n" )
+    end
+    
+    def create_record_for_resource(resource) #:nodoc:
+      update_and_save_record_for_resource(new(remote_foreign_key => resource.send(remote_primary_key)), resource)
+    end
+    
+    def time_of_update(resource)
+      (resource.respond_to?(:deleted_at) && resource.deleted_at) ? resource.deleted_at : resource.updated_at
+    end
+    
+    def deleted?(resource)
+      resource.respond_to?(:deleted_at) && resource.deleted_at && resource.deleted_at <= Time.now
+    end
+
+  end  
+end

data/lib/has_remote/synchronization.rb

@@ -0,0 +1,15 @@
+module HasRemote
+  
+  class Synchronization < ActiveRecord::Base #:nodoc:
+    set_table_name 'has_remote_synchronizations'
+    
+    named_scope :for, lambda { |model_name| {:conditions => ["model_name = ?", model_name.to_s.classify] } } do
+      def latest_change
+        self.find(:first, :order => 'latest_change DESC').latest_change rescue nil
+      end
+    end
+    
+    validates_presence_of :model_name, :latest_change
+  end
+  
+end

data/lib/has_remote.rb

@@ -0,0 +1,234 @@
+# The main module for the has_remote plugin. Please see README for more information.
+#
+module HasRemote
+  
+  def self.included(base) #:nodoc:
+    base.extend ClassMethods
+  end
+  
+  # Returns an array of all models that have a remote.
+  #
+  def self.models
+    # Make sure all models are loaded:
+    Dir[File.join(RAILS_ROOT, 'app', 'models', '*.rb')].each { |f| require_dependency f }
+
+    @models ||= []
+  end
+  
+  # Updates cached attributes, destroys deleted records and adds new records of all models that have a remote.
+  # Also see HasRemote::Synchronizable.
+  #
+  def self.synchornize!
+    models.each(&:synchronize!)
+  end
+      
+  module ClassMethods
+    
+    # Gives your local ActiveRecord model a remote proxy (ActiveResource::Base),
+    # which enables you to look for certain attributes remotely.
+    # 
+    # ==== Options
+    # 
+    # [:foreign_key]  The name of the column used to store the id of the remote resource. Defaults to :remote_id.
+    # [:remote_primary_key]  The name of the remote resource's primary key. Defaults to :id.
+    # [:site, :user, :password, ...]  Basically all ActiveResource configuration settings are available,
+    #                                 see http://api.rubyonrails.org/classes/ActiveResource/Base.html      
+    # [:through]     Optional custom ActiveResource class name to use for the proxy. If not set, a default class called
+    #                "<ModelName>::Remote" will be created dynamically. *Note* that any ActiveResource
+    #                configuration options will still be applied to this class.
+    #
+    # ==== Usage
+    #
+    #  class User < ActiveRecord::Base
+    #    has_remote :site => 'http://people.local'
+    #  end
+    #
+    #  # In a migration:
+    #  add_column :users, :remote_id, :integer
+    #
+    #  User.find(1).remote
+    #  # => #<User::Remote> (inherits from ActiveResource::Base)
+    #  User.find(1).remote.username
+    #  # => "User name from remote server"
+    #
+    # has_remote also takes a block which is passed in a HasRemote::Config object which can be used to specify
+    # remote attributes:
+    #
+    #  class User < ActiveRecord::Base
+    #    has_remote :site => '...' do |remote|
+    #      remote.attribute :username
+    #      remote.attribute :full_name, :local_cache => true
+    #      remote.attribute :email_address, :as => :email
+    #    end 
+    #  end
+    #
+    #  User.find(1).username
+    #  # => "User name from remote server"
+    #
+    def has_remote(options, &block)
+      unless options[:through] || self.const_defined?("Remote")
+        self.const_set("Remote", ActiveResource::Base.clone)
+      end
+      
+      @remote_class = options[:through] ? options.delete(:through).constantize : self::Remote
+      
+      @remote_foreign_key = options.delete(:foreign_key) || :remote_id
+      
+      @remote_primary_key = options.delete(:remote_primary_key) || :id
+      
+      # create extra class methods
+      class << self
+        attr_reader :remote_class
+        attr_reader :remote_foreign_key
+        attr_reader :remote_finder
+        attr_reader :remote_primary_key
+        attr_writer :remote_attribute_aliases
+        
+        def remote_attributes # :nodoc:
+          @remote_attributes ||= []
+        end
+        
+        def remote_attribute_aliases # :nodoc:
+          @remote_attribute_aliases ||= {}
+        end
+        
+        include HasRemote::Synchronizable
+      end
+      
+      # set ARes to look for correct resource (only if not manually specified)
+      unless options[:element_name] || @remote_class.element_name != "remote"
+        @remote_class.element_name = self.name.underscore.split('/').last
+      end
+      
+      # setup ARes class with given options
+      options.each do |option, value|
+        @remote_class.send "#{option}=", value 
+      end
+      
+      attr_accessor :skip_update_cache
+      
+      block.call( Config.new(self) ) if block_given?
+            
+      include InstanceMethods
+      HasRemote.models << self
+    end
+    
+  end
+  
+  module InstanceMethods
+    
+    # Returns the remote proxy for this record as an <tt>ActiveResource::Base</tt> object. Returns nil
+    # if foreign key is nil. 
+    #
+    # *Arguments*
+    #
+    # - <tt>force_reload</tt>:  Forces a reload from the remote server if set to true. Defaults to false.
+    #
+    def remote(force_reload = false)
+      if force_reload || @remote.nil?
+        id = self.send(self.class.remote_foreign_key)
+        @remote = id ? (self.class.remote_finder ? self.class.remote_finder[id] : self.class.remote_class.find(id)) : nil
+      end
+      @remote
+    end
+    
+    # Checks whether a remote proxy exists.
+    #
+    def has_remote?
+      # NOTE ARes#exists? is broken:
+      # https://rails.lighthouseapp.com/projects/8994/tickets/1223-activeresource-head-request-sends-headers-with-a-nil-key
+      #
+      return !remote(true).nil? rescue false
+    end
+    
+    # Synchronizes all locally cached remote attributes to this object and saves the object.
+    #
+    def update_cached_attributes!
+      update_cached_attributes
+      save!
+    end
+    
+    # Synchronizes all locally cached remote attributes to this object, but does not save the object.
+    #
+    # Note that when the remote does no longer exist, all remote attributes will be
+    # set to nil.
+    #
+    def update_cached_attributes
+      unless self.skip_update_cache || self.class.cached_attributes.empty?
+        self.class.cached_attributes.each do |remote_attr|
+          local_attr = self.class.remote_attribute_aliases[remote_attr] || remote_attr
+          write_attribute(local_attr, has_remote? ? remote(true).send(remote_attr) : nil)
+        end
+      end
+    end
+    
+  end
+  
+  class Config
+    def initialize(base) #:nodoc:
+      @base = base
+    end
+    
+    # Defines a remote attribute. Adds a getter method on instances, which delegates to the remote object.
+    #
+    # *Options*
+    #
+    # [:local_cache]  If set to true the attribute will also be saved locally. See README for more information
+    #                 about caching and synchronization.
+    # [:as]           Optionally map remote attribute to this name.
+    #
+    # *Example*
+    # 
+    #  class User < ActiveRecord::Base
+    #    has_remote :site => '...' do |remote|
+    #      remote.attribute :name, :local_cache => true
+    #      remote.attribute :email, :as => :email_address
+    #    end
+    #  end
+    #
+    def attribute(attr_name, options = {})
+      method_name = options[:as] || attr_name
+      
+      @base.remote_attributes << attr_name
+      @base.remote_attribute_aliases = @base.remote_attribute_aliases.merge(attr_name => method_name)
+      
+      unless options[:local_cache]
+        @base.class_eval <<-RB
+
+          def #{method_name}
+            remote.try(:#{attr_name})
+          end
+
+          def #{method_name}=(arg)
+            raise NoMethodError.new("Remote attributes can't be set directly in this version of has_remote.")
+          end
+
+        RB
+      else
+        @base.cached_attributes << attr_name
+      end
+      
+    end
+    
+    # Lets you specify custom finder logic to find the record's remote object.
+    # It takes a block which is passed in the id of the remote object.
+    #
+    # (By default <tt>Model.remote_class.find(id)</tt> would be called.)
+    #
+    # *Example*
+    #
+    #  class User < ActiveRecord::Base
+    #    has_remote :site => "..." do |remote|
+    #      remote.finder do |id|
+    #        User::Remote.find :one, :from => "users/active/#{id}.xml"
+    #      end
+    #    end
+    #  end
+    #
+    def finder(&block)
+      @base.instance_variable_set "@remote_finder", block
+    end
+    
+  end
+  
+end

data/lib/tasks/has_remote.rake

@@ -0,0 +1,12 @@
+namespace :hr do
+
+  desc 'Synchronizes all attributes locally cached by has_remote'
+  task :sync => :environment do
+    models = ENV['MODELS'].nil? ? HasRemote.models : extract_models
+    models.each(&:synchronize!)
+  end
+
+  def extract_models
+    ENV['MODELS'].split(',').map(&:constantize)
+  end
+end

data/shoulda_macros/has_remote_macros.rb

@@ -0,0 +1,21 @@
+module HasRemoteMacros
+
+  def should_have_remote(&block)
+    klass = model_class
+    should "have remote resources" do
+      assert HasRemote.models.include?(klass)
+    end
+  end
+
+  def should_have_remote_attribute(attr_name, options = {})
+    klass = model_class
+    should "have remote attribute #{attr_name}" do
+      assert klass.remote_attributes.include?(attr_name)
+      assert klass.cached_attributes.include?(attr_name) if options[:local_cache]
+      assert klass.new.respond_to?(options[:as] || attr_name)
+    end
+  end
+
+end
+
+Test::Unit::TestCase.extend HasRemoteMacros

data/spec/caching_spec.rb

@@ -0,0 +1,179 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+context "Given existing remote resources" do
+  
+  before(:each) do
+    User.delete_all
+    stub_resource 1, :email => "joeremote@foo.bar"
+    stub_resource 2, :email => "jane_remote@foo.bar"
+  end
+  
+  describe "a user" do
+    
+    it "should return cached attributes" do
+      User.should respond_to(:cached_attributes)
+      User.cached_attributes.should include(:email)
+    end
+    
+    it "should return changed remotes since yesterday" do
+      user_1, user_2 = mock(:user), mock(:user)
+      time = 1.day.ago
+      User::Remote.should_receive(:find).with(:all,{:from => :updated, :params=>{:since=>time.to_s}}).once.and_return([user_1, user_2])
+      
+      User.should respond_to(:changed_remotes_since)
+      User.changed_remotes_since(time).should include(user_1, user_2)
+    end
+    
+    it "should find last synchronization time" do
+      times = []
+      1.upto(3) do |i|
+        times << i.days.ago
+        HasRemote::Synchronization.create(:model_name => 'HasRemoteSpec::User', :latest_change => times.last)
+      end
+      User.should respond_to(:synchronized_at)
+      User.synchronized_at.to_s.should == times.first.to_s
+    end
+        
+    it "should not delegate cached remote attributes" do
+      user = User.create! :remote_id => 1
+      User::Remote.should_not_receive(:find)
+      user.email.should == "joeremote@foo.bar"
+    end
+    
+    it "should update its cached remote attributes on save" do
+      user = User.create! :remote_id => 1
+      user[:email].should == "joeremote@foo.bar"
+      user.update_attributes(:remote_id => 2)
+      user[:email].should == "jane_remote@foo.bar"   
+    end
+
+    it "should not update its cached remote attributes if skip_update_cache is true" do
+      user = User.create! :remote_id => 1, :skip_update_cache => true
+      user[:email].should == nil
+    end
+    
+  end
+
+  describe "synchronization" do
+  
+    describe "for the User model" do
+    
+      describe "with updated and deleted remotes" do
+        
+        before(:each) do
+          @user_1, @user_2, @user_3 = User.create!(:remote_id => 1), User.create!(:remote_id => 2), User.create!(:remote_id => 3)
+        
+          @yesterday = DateTime.parse 1.day.ago.to_s
+        
+          resources = [
+            mock(:user, :id => 1, :email => "changed@foo.bar", :updated_at => @yesterday),
+            mock(:user, :id => 2, :email => "altered@foo.bar", :updated_at => 2.days.ago, :deleted_at => nil),
+            mock(:user, :id => 3, :email => "deleted@foo.bar", :updated_at => 2.days.ago, :deleted_at => 2.days.ago),
+            mock(:user, :id => 4, :email => "new@foo.bar", :updated_at => @yesterday),
+            mock(:user, :id => 5, :email => "new-deleted@foo.bar", :updated_at => 2.days.ago, :deleted_at => 2.days.ago),
+          ]
+          User.stub!(:changed_remotes_since).and_return(resources)
+        
+          lambda { User.synchronize! }.should change(HasRemote::Synchronization, :count).by(1)
+        end
+        
+        it "should keep track of the last synchronization" do
+          HasRemote::Synchronization.for("HasRemoteSpec::User").latest_change.should == @yesterday
+        end
+    
+        it "should update changed users" do
+          @user_1.reload[:email].should == "changed@foo.bar"
+          @user_2.reload[:email].should == "altered@foo.bar"
+        end
+      
+        it "should destroy deleted users" do
+          User.exists?(@user_3).should be_false
+        end
+      
+        it "should create added users" do
+          User.exists?(:remote_id => 4).should be_true
+        end
+        
+        it "should not create deleted users" do
+          User.exists?(:remote_id => 5).should be_false
+        end
+      end
+      
+      describe "that fails" do
+        
+        before(:each) do
+          
+          @failure = lambda {
+            user_1, user_2 = User.create!(:remote_id => 1), User.create!(:remote_id => 2)
+
+            yesterday = DateTime.parse 1.day.ago.to_s
+
+            resources = [
+              mock(:user, :id => 1, :email => "changed@foo.bar", :updated_at => yesterday),
+              mock(:user, :id => 2, :email => "altered@foo.bar", :updated_at => 2.days.ago)
+            ]
+            
+            User.stub!(:changed_remotes_since).and_return(resources)
+            
+            resources.last.should_receive(:send).and_raise "All hell breaks loose" # Raise when attr is read from resource 2.
+            
+            User.synchronize!
+          }
+        end
+        
+        it "should do it silently" do
+          @failure.should_not raise_error
+        end
+      
+        it "should not create a synchronization record" do
+          @failure.should_not change(HasRemote::Synchronization, :count)
+        end
+        
+      end
+    
+    end
+  
+    describe "for a single user" do
+    
+      it "should update the user" do
+        user = User.create! :remote_id => 1
+        user[:email].should == "joeremote@foo.bar"
+        
+        stub_resource 1, :email => "changed@foo.bar"
+        
+        user.update_cached_attributes!
+        user[:email].should == "changed@foo.bar"
+      end
+    
+    end
+  
+  end
+  
+  describe "synchronizing new cheeses" do
+    before do
+      resources = [
+        mock(:cheese, :id => 1, :name => "Brie", :updated_at => Date.yesterday)
+      ]
+      Cheese.stub!(:changed_remotes_since).and_return(resources)
+      lambda{ Cheese.synchronize! }.should change(Cheese, :count).from(0).to(1)
+    end
+    
+    after { Cheese.delete_all }
+        
+    it "should populate the local 'maturity' attribute with its default database value" do
+      Cheese.first.maturity.should == 5
+    end
+    
+    it "should populate the local 'smell' attribute with the value set inside of a before_validation callback" do
+      Cheese.first.smell.should == 5 * 10 
+    end
+    
+  end
+  
+end
+
+def stub_resource(id, attrs)
+  resource = mock(:user, {:id => id}.merge(attrs))
+  User::Remote.stub!(:find).with(id).and_return(resource)
+  resource
+end

data/spec/database.yml

@@ -0,0 +1,3 @@
+test:
+  adapter: sqlite3
+  database: ":memory:"

data/spec/has_remote_spec/book.rb

@@ -0,0 +1,7 @@
+module HasRemoteSpec
+  class RemoteBook < ActiveResource::Base; end
+  
+  class Book < ActiveRecord::Base   
+    has_remote :through => "HasRemoteSpec::RemoteBook", :foreign_key => :custom_remote_id
+  end
+end

data/spec/has_remote_spec/cheese.rb

@@ -0,0 +1,10 @@
+module HasRemoteSpec
+  class Cheese < ActiveRecord::Base
+    validates_presence_of :maturity, :smell
+    has_remote :site => "http://dummy.local"
+    
+    def before_validation_on_create
+      self.smell = self.maturity * 10 if self.smell.nil?
+    end
+  end
+end

data/spec/has_remote_spec/product.rb

@@ -0,0 +1,9 @@
+module HasRemoteSpec
+  class Product < ActiveRecord::Base
+    has_remote :site => "http://dummy.local" do |remote|
+      remote.finder do |id|
+        Product::Remote.find :one, :from => "/special/place/products/#{id}.xml"
+      end
+    end
+  end
+end

data/spec/has_remote_spec/user.rb

@@ -0,0 +1,11 @@
+module HasRemoteSpec
+  class User < ActiveRecord::Base
+    has_remote :site => "http://dummy.local" do |remote|
+      remote.attribute :name
+      remote.attribute :email, :local_cache => true
+      remote.attribute :phone, :as => :telephone
+    end
+    
+    before_save :update_cached_attributes
+  end
+end

data/spec/has_remote_spec.rb

@@ -0,0 +1,108 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe HasRemote do
+  
+  it "should know about registered models" do
+    HasRemote.should respond_to(:models)
+    HasRemote.models.should include(User, Book)
+  end
+  
+end
+
+describe User do
+ 
+  it "should respond to 'remote_class' and 'remote_foreign_key'" do
+    User.should respond_to(:remote_class, :remote_foreign_key)
+    User.remote_class.should == User::Remote
+    User.remote_foreign_key.should == :remote_id
+  end
+  
+  it "should set remote class' configuration" do
+     User.remote_class.site.should_not be_nil
+     User.remote_class.element_name.should == "user"
+  end
+  
+  it "should return remote attributes" do
+    User.remote_attributes.should include(:name, :email)
+  end
+
+  it "should return remote attribute aliases" do
+    User.remote_attribute_aliases[:name].should == :name
+    User.remote_attribute_aliases[:phone].should == :telephone
+  end
+
+  describe "instances" do
+
+    before(:each) do
+      @user = User.new
+      @user.remote_id = 1
+    end
+
+    it "should have a generated remote" do
+      User::Remote.should_receive(:find).twice.with(1).and_return( mock(:resource, :name => "John") )
+
+      @user.should respond_to(:remote)
+      @user.remote.should respond_to(:name)
+      @user.has_remote?.should be_true
+    end
+
+    it "should delegate remote attribute" do
+      User::Remote.should_receive(:find).once.with(1).and_return( mock(:resource, :name => "John") )
+
+      @user.should respond_to(:name)
+      @user.name.should == "John"
+    end
+
+    context "without a remote" do
+      
+      before(:each) do
+        @user.remote_id = nil
+      end
+
+      it "should return nil for remote attributes" do
+        @user.remote.should be_nil
+        @user.name.should be_nil
+      end
+    end
+  end
+end
+
+describe Book do
+  
+  it "should use a custom remote key" do
+    Book.remote_foreign_key.should == :custom_remote_id
+  end
+  
+  describe "instances" do
+    
+    it "should have a custom remote" do
+      @book = Book.new
+      @book.custom_remote_id = 1
+
+      HasRemoteSpec::RemoteBook.should_receive(:find).twice.with(1).and_return( mock(:resource, :title => "Ruby for Rails") )
+
+      @book.should respond_to(:remote)
+      @book.remote.should respond_to(:title)
+      @book.has_remote?.should be_true
+    end    
+  end
+end
+
+describe Product do
+  
+  it "should have a custom finder" do
+    Product.should respond_to(:remote_finder)
+    Product.remote_finder.should be_a(Proc)
+  end
+  
+  describe "instances" do
+    
+    it "should use a custom finder" do
+      @product = Product.new :remote_id => 1
+      Product::Remote.should_receive(:find).once.with(:one, :from => "/special/place/products/1.xml").and_return("resource")
+      
+      @product.remote.should == "resource"
+    end
+  end
+  
+end

data/spec/schema.rb

@@ -0,0 +1,29 @@
+ActiveRecord::Migration.verbose = false
+
+ActiveRecord::Schema.define(:version => 0) do
+  create_table :books do |t|
+    t.integer :custom_remote_id
+  end
+  
+  create_table :users do |t|
+    t.integer :remote_id
+    t.string  :email
+  end
+  
+  create_table :products do |t|
+    t.integer :remote_id
+  end
+
+  create_table :has_remote_synchronizations do |t|
+    t.string   :model_name, :null => false
+    t.datetime :latest_change, :null => false
+    t.datetime :created_at
+  end
+  
+  create_table :cheeses do |t|
+    t.string  :name
+    t.integer :maturity, :default => 5
+    t.integer :smell
+    t.integer :remote_id
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,38 @@
+# Fake Rails constants
+RAILS_ENV  = ENV["RAILS_ENV"] ||= 'test'
+RAILS_ROOT = File.dirname(__FILE__)
+
+# Include required libraries
+require 'rubygems'
+require 'active_record'
+require 'active_resource'
+require 'shoulda/active_record/matchers'
+include Shoulda::ActiveRecord::Matchers
+
+# Include plugin's files
+require File.dirname(__FILE__) + '/../lib/has_remote'
+require File.dirname(__FILE__) + '/../lib/has_remote/synchronizable'
+require File.dirname(__FILE__) + '/../lib/has_remote/synchronization'
+
+# Initialize plugin
+require "#{File.dirname(__FILE__)}/../init"
+
+# Create logger
+ActiveRecord::Base.logger = Logger.new(File.dirname(__FILE__) + "/debug.log")
+
+# Setup database connection and structure
+config = YAML::load(IO.read(File.dirname(__FILE__) + '/database.yml'))
+ActiveRecord::Base.establish_connection(config[ENV['RAILS_ENV']])
+load(File.dirname(__FILE__) + "/schema.rb")
+
+# Require models
+require File.dirname(__FILE__) + '/has_remote_spec/user'
+require File.dirname(__FILE__) + '/has_remote_spec/book'
+require File.dirname(__FILE__) + '/has_remote_spec/product'
+require File.dirname(__FILE__) + '/has_remote_spec/cheese'
+
+# Create schortcuts 
+User = HasRemoteSpec::User
+Book = HasRemoteSpec::Book
+Product = HasRemoteSpec::Product
+Cheese  = HasRemoteSpec::Cheese

data/spec/synchronization_spec.rb

@@ -0,0 +1,11 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe HasRemote::Synchronization do
+  
+  subject { HasRemote::Synchronization.new }
+    
+  it { should validate_presence_of(:model_name) }
+  it { should validate_presence_of(:latest_change) }
+  it { should have_named_scope("for('User')") }
+
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification 
+name: HasRemote
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Sjoerd Andringa
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-01-18 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: Bind a remote ActiveResource object to your local ActiveRecord objects, delegate attributes and optionally cache remote attributes locally.
+email: sjoerd.andringa@innovationfactory.eu
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+- TODO
+files: 
+- .gitignore
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+- TODO
+- VERSION
+- init.rb
+- lib/generators/has_remote_migration/has_remote_migration_generator.rb
+- lib/generators/has_remote_migration/templates/create_has_remote_synchronizations.erb
+- lib/has_remote.rb
+- lib/has_remote/synchronizable.rb
+- lib/has_remote/synchronization.rb
+- lib/tasks/has_remote.rake
+- shoulda_macros/has_remote_macros.rb
+- spec/caching_spec.rb
+- spec/database.yml
+- spec/has_remote_spec.rb
+- spec/has_remote_spec/book.rb
+- spec/has_remote_spec/cheese.rb
+- spec/has_remote_spec/product.rb
+- spec/has_remote_spec/user.rb
+- spec/schema.rb
+- spec/spec_helper.rb
+- spec/synchronization_spec.rb
+has_rdoc: true
+homepage: http://github.com/innovationfactory/has_remote
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Bind a remote ActiveResource object to your local ActiveRecord objects.
+test_files: 
+- spec/caching_spec.rb
+- spec/has_remote_spec/book.rb
+- spec/has_remote_spec/cheese.rb
+- spec/has_remote_spec/product.rb
+- spec/has_remote_spec/user.rb
+- spec/has_remote_spec.rb
+- spec/schema.rb
+- spec/spec_helper.rb
+- spec/synchronization_spec.rb