HasRemote 0.1.7 → 0.2.0

data/lib/has_remote/railtie.rb

@@ -0,0 +1,21 @@
+require 'rails'
+
+module HasRemote
+  # @private
+  class Railtie < Rails::Railtie  #:nodoc:
+    initializer 'has_remote.load' do
+      ActiveSupport.on_load(:active_record) do
+        HasRemote::Railtie.load!
+      end
+    end
+
+    rake_tasks do
+      load 'tasks/has_remote.rake'
+    end
+
+    def self.load!
+      ActiveRecord::Base.send :include, HasRemote
+      ActiveSupport.run_load_hooks(:has_remote)
+    end
+  end
+end

data/lib/has_remote/synchronizable.rb

@@ -1,8 +1,8 @@
 module HasRemote
 
-  # Contains class methods regarding synchronization of changed, added and deleted remotes.
+  # Contains class methods regarding synchronization of changed, added and deleted remote data.
   #
-  # === Synchronization examples
+  # ==== Synchronization examples:
   #
   # Update all cached attributes, destroy deleted records and add new records for all models that have a remote:
   #  HasRemote.synchronize!
@@ -17,12 +17,15 @@ module HasRemote
   #  @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.
+  # your cache is up to date.
   #
-  # *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.
+  # You can also use a rake task to synchronize from the command line:
+  #  rake hr:sync
+  #
+  # See the {file:README.rdoc README} for more rake options.
+  #
+  # @note All remote resources need to have an <tt>updated_at</tt> field in order for synchronization to work. Optionally, records will
+  #       be destroyed if their remote has a <tt>deleted_at</tt> field and its time lies before the time of synchronization.
   #
   module Synchronizable
 
@@ -32,44 +35,40 @@ module HasRemote
       @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>&last_record_id=<id>' on your resources URL, where 'time' is
-    # the updated_at value of the last processed remote object and 'last_record_id' is its id.
-    #
-    # *Options*
+    # Returns all remote objects that have been changed since the last synchornization _(or since ever if no
+    # time is given)_. This may include new and optionally deleted (tagged by a <tt>deleted_at</tt> attribute) resources.
     #
-    # The options passed in to <tt>synchronize!</tt> will be passed through to <tt>updated_remotes</tt>.
-    # By default they are used as request parameters for remotely requesting the updated records.
+    # This method is called from the {#synchronize!} class method. By default
+    # it queries <tt>/updated?since=[time]&last_record_id=[id]</tt> on your resources URL, where <tt>time</tt> is
+    # the updated_at value of the last processed remote object and <tt>last_record_id</tt> is its ID.
     #
-    # 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.:
+    # *Important:* If you are using synchronization you'll probably need to override this method in your model to match
+    # your host's REST API; here's an example of another implementation:
     #
     #  def self.updated_remotes(options = nil)
     #    time = last_synchronization.try(:last_record_updated_at) || 12.hours.ago
     #    User::Remote.find :all, :from => :search, :params => { :updated_since => time.to_s(:db) }
     #  end
     #
-    def updated_remotes( options = {} )
+    # @param [Hash] parameters The parameter options passed in to {#synchronize!} will be passed through to this method.
+    #               They are used as request parameters for remotely requesting the updated records.
+    #
+    def updated_remotes( parameters = {} )
       time = last_synchronization.try(:last_record_updated_at) || DateTime.parse("Jan 1 1970")
-      remote_class.find :all, :from => :updated, :params => { :since => time.to_s, :last_record_id => last_synchronization.try(:last_record_id) }.merge( options )
+      remote_class.find :all, :from => :updated, :params => { :since => time.to_s, :last_record_id => last_synchronization.try(:last_record_id) }.merge( parameters )
     end
 
     # Will update all records that have been created, updated or deleted on the remote host
     # since the last successful synchronization.
     #
-    # *Options*
-    #
-    # Options are passed through to <tt>updated_remotes</tt> which is called in order to fetch the updated records.
-    # Use this if you want to override its default options.
+    # @param [Hash] parameters Parameter options are passed through to {#updated_remotes}. There they are used
+    #               as request parameters for remotely requesting the updated records.
     #
-    def synchronize!(options = {})
+    def synchronize!(parameters = {})
       logger.info( "*** Start synchronizing #{table_name} at #{Time.now.to_s :long} ***\n" )
       @sync_count = 0
       begin
-        changed_objects = updated_remotes( options )
+        changed_objects = updated_remotes( parameters )
         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) }
@@ -90,7 +89,9 @@ module HasRemote
       end
     end
 
-    # The last successful synchronization for this model.
+    # Returns the record for last successful synchronization for this model.
+    #
+    # @return [Synchronization]
     #
     def last_synchronization
       HasRemote::Synchronization.for(self.name).last
@@ -142,11 +143,11 @@ module HasRemote
       update_and_save_record_for_resource(new(remote_foreign_key => resource.send(remote_primary_key)), resource)
     end
 
-    def time_updated(resource)
+    def time_updated(resource) #:nodoc:
       (resource.respond_to?(:deleted_at) && resource.deleted_at) ? resource.deleted_at : resource.updated_at
     end
 
-    def deleted?(resource)
+    def deleted?(resource) #:nodoc:
       resource.respond_to?(:deleted_at) && resource.deleted_at && resource.deleted_at <= Time.now
     end
 

data/lib/has_remote/synchronization.rb

@@ -1,9 +1,18 @@
 module HasRemote
 
+  # This model represents a synchronization performed by HasRemote.
+  #
+  # ==== Attributes:
+  #
+  # [model_name] (String) Name of the model that was synchronized.
+  # [last_record_updated_at] (Time) Timestamp representing the <tt>updated_at</tt> of the last record that was synchronized during this synchronization.
+  # [last_record_id] (Integer) ID of the last record that was synchronized during this synchronization.
+  # [created_at] (Time) time when this synchronization finished.
+  #
   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] } }
+    scope :for, lambda { |model_name| where(:model_name => model_name.to_s.classify) }
 
     validates_presence_of :model_name, :last_record_updated_at, :last_record_id
   end

data/shoulda_macros/has_remote_macros.rb

@@ -1,21 +1,23 @@
-module HasRemoteMacros
+module HasRemote
+  module ShouldaMacros
 
-  def should_have_remote(&block)
-    klass = model_class
-    should "have remote resources" do
-      assert HasRemote.models.include?(klass)
+    def should_have_remote
+      klass = model_class
+      should "have remote resources" do
+        assert HasRemote.models.include?(klass)
+      end
     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)
+    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
 
+  end
 end
 
-Test::Unit::TestCase.extend HasRemoteMacros
+Test::Unit::TestCase.extend HasRemote::ShouldaMacros

data/spec/caching_spec.rb

@@ -1,6 +1,6 @@
 require File.dirname(__FILE__) + '/spec_helper.rb'
 
-context "Given existing remote resources" do
+describe "Given existing remote resources" do
 
   before(:each) do
     User.delete_all
@@ -27,7 +27,7 @@ context "Given existing remote resources" do
     it "should find last synchronization" do
       times = []
       3.downto(1) do |i|
-        HasRemote::Synchronization.create(:model_name => 'HasRemoteSpec::User', :last_record_updated_at => i.days.ago, :last_record_id => i)
+        HasRemote::Synchronization.create!(:model_name => 'User', :last_record_updated_at => i.days.ago, :last_record_id => i)
       end
       User.should respond_to(:last_synchronization)
       sync = User.last_synchronization
@@ -62,16 +62,14 @@ context "Given existing remote resources" do
       describe "with updated and deleted remotes" do
 
         before(:each) do
-          @yesterday = DateTime.parse 1.day.ago.to_s
-          @last_id   = 5
-          @user_1, @user_2, @user_3 = User.create!(:remote_id => @last_id), User.create!(:remote_id => 1), User.create!(:remote_id => 2)
+          @yesterday = 1.day.ago
+          @user_1, @user_2 = User.create!(:remote_id => 1), User.create!(:remote_id => 2)
 
           resources = [
             mock(:user, :id => 1, :email => "altered@foo.bar", :updated_at => 2.days.ago, :deleted_at => nil),
             mock(:user, :id => 2, :email => "deleted@foo.bar", :updated_at => 2.days.ago, :deleted_at => 2.days.ago),
             mock(:user, :id => 3, :email => "new-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 => @last_id, :email => "changed@foo.bar", :updated_at => @yesterday)
           ]
           User.stub!(:updated_remotes).and_return(resources)
 
@@ -79,19 +77,18 @@ context "Given existing remote resources" do
         end
 
         it "should keep track of the last synchronized record" do
-          sync = HasRemote::Synchronization.for("HasRemoteSpec::User").last
+          sync = HasRemote::Synchronization.for("User").last
 
           sync.last_record_updated_at.should == @yesterday
-          sync.last_record_id.should == @last_id
+          sync.last_record_id.should == 4
         end
 
         it "should update changed users" do
-          @user_1.reload[:email].should == "changed@foo.bar"
-          @user_2.reload[:email].should == "altered@foo.bar"
+          @user_1.reload[:email].should == "altered@foo.bar"
         end
 
         it "should destroy deleted users" do
-          User.exists?(@user_3).should be_false
+          User.exists?(@user_2).should be_false
         end
 
         it "should create added users" do

data/spec/has_remote_spec.rb

@@ -1,27 +1,27 @@
 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
@@ -54,7 +54,7 @@ describe User do
     end
 
     context "without a remote" do
-      
+
       before(:each) do
         @user.remote_id = nil
       end
@@ -68,41 +68,41 @@ describe User do
 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") )
+      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
 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/spec_helper.rb

@@ -1,38 +1,23 @@
-# 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'
+require 'bundler/setup'
 
 # Initialize plugin
-require "#{File.dirname(__FILE__)}/../init"
+require "rails"
+Rails.env  = ENV["RAILS_ENV"] ||= 'test'
+require "shoulda-matchers"
+require "active_record"
+require "active_resource"
+require "has_remote"
+require "has_remote/railtie"
+HasRemote::Railtie.load!
 
 # Create logger
-ActiveRecord::Base.logger = Logger.new(File.dirname(__FILE__) + "/debug.log")
+ActiveRecord::Base.logger = ActiveSupport::BufferedLogger.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']])
+ActiveRecord::Base.establish_connection(config[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
+# Require test models
+Dir[File.join(File.dirname(__FILE__), "support", "**/*.rb")].each { |file| require file }

data/spec/support/book.rb

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

data/spec/support/cheese.rb

@@ -0,0 +1,11 @@
+class Cheese < ActiveRecord::Base
+  validates_presence_of :maturity, :smell
+  has_remote :site => "http://dummy.local"
+  before_validation :set_smell, :on => :create
+
+  protected
+
+  def set_smell
+    self.smell = self.maturity * 10 if self.smell.nil?
+  end
+end

data/spec/support/product.rb

@@ -0,0 +1,7 @@
+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

data/spec/support/user.rb

@@ -0,0 +1,9 @@
+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

data/spec/synchronization_spec.rb

@@ -10,10 +10,11 @@ describe HasRemote::Synchronization do
 
   describe "named scope 'for'" do
     before do
+      HasRemote::Synchronization.delete_all
       @user_synchronization = HasRemote::Synchronization.create! :model_name => 'User', :last_record_updated_at => 1.day.ago, :last_record_id => 1
       @book_synchronization = HasRemote::Synchronization.create! :model_name => 'Book', :last_record_updated_at => 1.day.ago, :last_record_id => 2
     end
-    
+
     it "should return synchronization records scoped by model_name" do
       HasRemote::Synchronization.for('User').should == [@user_synchronization]
     end