HasRemote 0.1.7 → 0.2.0

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format=d

data/.yardopts

@@ -0,0 +1 @@
+--exclude lib/generators --no-private --protected lib/**/*.rb - README.rdoc

data/Gemfile

@@ -0,0 +1,10 @@
+source "http://rubygems.org"
+
+gem 'rails', '>= 3.0.0'
+
+group :development do
+  gem 'sqlite3', '>= 1.3.4'
+  gem 'jeweler', '>= 1.6.4'
+  gem 'rspec', '>= 2.6.0'
+  gem 'shoulda-matchers', '>= 1.0.0.beta3'
+end

data/Gemfile.lock

@@ -0,0 +1,93 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    abstract (1.0.0)
+    actionmailer (3.0.0)
+      actionpack (= 3.0.0)
+      mail (~> 2.2.5)
+    actionpack (3.0.0)
+      activemodel (= 3.0.0)
+      activesupport (= 3.0.0)
+      builder (~> 2.1.2)
+      erubis (~> 2.6.6)
+      i18n (~> 0.4.1)
+      rack (~> 1.2.1)
+      rack-mount (~> 0.6.12)
+      rack-test (~> 0.5.4)
+      tzinfo (~> 0.3.23)
+    activemodel (3.0.0)
+      activesupport (= 3.0.0)
+      builder (~> 2.1.2)
+      i18n (~> 0.4.1)
+    activerecord (3.0.0)
+      activemodel (= 3.0.0)
+      activesupport (= 3.0.0)
+      arel (~> 1.0.0)
+      tzinfo (~> 0.3.23)
+    activeresource (3.0.0)
+      activemodel (= 3.0.0)
+      activesupport (= 3.0.0)
+    activesupport (3.0.0)
+    arel (1.0.1)
+      activesupport (~> 3.0.0)
+    builder (2.1.2)
+    diff-lcs (1.1.2)
+    erubis (2.6.6)
+      abstract (>= 1.0.0)
+    git (1.2.5)
+    i18n (0.4.2)
+    jeweler (1.6.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+    mail (2.2.19)
+      activesupport (>= 2.3.6)
+      i18n (>= 0.4.0)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    mime-types (1.16)
+    polyglot (0.3.2)
+    rack (1.2.3)
+    rack-mount (0.6.14)
+      rack (>= 1.0.0)
+    rack-test (0.5.7)
+      rack (>= 1.0)
+    rails (3.0.0)
+      actionmailer (= 3.0.0)
+      actionpack (= 3.0.0)
+      activerecord (= 3.0.0)
+      activeresource (= 3.0.0)
+      activesupport (= 3.0.0)
+      bundler (~> 1.0.0)
+      railties (= 3.0.0)
+    railties (3.0.0)
+      actionpack (= 3.0.0)
+      activesupport (= 3.0.0)
+      rake (>= 0.8.4)
+      thor (~> 0.14.0)
+    rake (0.9.2)
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.4)
+    rspec-expectations (2.6.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.6.0)
+    shoulda-matchers (1.0.0.beta3)
+    sqlite3 (1.3.4)
+    thor (0.14.6)
+    treetop (1.4.10)
+      polyglot
+      polyglot (>= 0.3.1)
+    tzinfo (0.3.29)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  jeweler (>= 1.6.4)
+  rails (>= 3.0.0)
+  rspec (>= 2.6.0)
+  shoulda-matchers (>= 1.0.0.beta3)
+  sqlite3 (>= 1.3.4)

data/HasRemote.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{HasRemote}
-  s.version = "0.1.7"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Sjoerd Andringa"]
-  s.date = %q{2010-12-28}
+  s.authors = [%q{Sjoerd Andringa}]
+  s.date = %q{2011-08-04}
   s.description = %q{Bind a remote ActiveResource object to your local ActiveRecord objects, delegate attributes and optionally cache remote attributes locally.}
   s.email = %q{sjoerd.andringa@innovationfactory.eu}
   s.extra_rdoc_files = [
@@ -17,57 +17,62 @@ Gem::Specification.new do |s|
     "TODO"
   ]
   s.files = [
+    ".rspec",
+    ".yardopts",
+    "Gemfile",
+    "Gemfile.lock",
     "HasRemote.gemspec",
     "MIT-LICENSE",
     "README.rdoc",
     "Rakefile",
     "TODO",
     "VERSION",
-    "generators/has_remote_migration/has_remote_migration_generator.rb",
-    "generators/has_remote_migration/templates/create_has_remote_synchronizations.erb",
-    "init.rb",
+    "lib/generators/has_remote/migration_generator.rb",
+    "lib/generators/has_remote/templates/create_has_remote_synchronizations.rb",
     "lib/has_remote.rb",
+    "lib/has_remote/railtie.rb",
     "lib/has_remote/synchronizable.rb",
     "lib/has_remote/synchronization.rb",
-    "lib/has_remote/tasks.rb",
-    "rails/init.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",
-    "tasks/rails.rake"
+    "spec/support/book.rb",
+    "spec/support/cheese.rb",
+    "spec/support/product.rb",
+    "spec/support/user.rb",
+    "spec/synchronization_spec.rb"
   ]
   s.homepage = %q{http://github.com/innovationfactory/has_remote}
-  s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.7}
+  s.require_paths = [%q{lib}]
+  s.rubygems_version = %q{1.8.6}
   s.summary = %q{Bind a remote ActiveResource object to your local ActiveRecord objects.}
-  s.test_files = [
-    "spec/caching_spec.rb",
-    "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"
-  ]
 
   if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<rails>, [">= 3.0.0"])
+      s.add_development_dependency(%q<sqlite3>, [">= 1.3.4"])
+      s.add_development_dependency(%q<jeweler>, [">= 1.6.4"])
+      s.add_development_dependency(%q<rspec>, [">= 2.6.0"])
+      s.add_development_dependency(%q<shoulda-matchers>, [">= 1.0.0.beta3"])
     else
+      s.add_dependency(%q<rails>, [">= 3.0.0"])
+      s.add_dependency(%q<sqlite3>, [">= 1.3.4"])
+      s.add_dependency(%q<jeweler>, [">= 1.6.4"])
+      s.add_dependency(%q<rspec>, [">= 2.6.0"])
+      s.add_dependency(%q<shoulda-matchers>, [">= 1.0.0.beta3"])
     end
   else
+    s.add_dependency(%q<rails>, [">= 3.0.0"])
+    s.add_dependency(%q<sqlite3>, [">= 1.3.4"])
+    s.add_dependency(%q<jeweler>, [">= 1.6.4"])
+    s.add_dependency(%q<rspec>, [">= 2.6.0"])
+    s.add_dependency(%q<shoulda-matchers>, [">= 1.0.0.beta3"])
   end
 end
 

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009-2010 Innovation Factory, Amsterdam
+Copyright (c) 2009-2011 Innovation Factory, Amsterdam
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -1,28 +1,32 @@
 = HasRemote
 
-Binds your local ActiveRecord objects to a remote ActiveResource object,
+Binds your local <tt>ActiveRecord</tt> objects to a remote <tt>ActiveResource</tt> object,
 which enables you to look for certain attributes remotely using a RESTful webservice.
 
 === Installation
 
-As a gem; Add the following to <tt>config/environment.rb</tt>:
+==== Rails 3
 
- config.gem 'HasRemote', :lib => 'has_remote'
+Add the following to your <tt>Gemfile</tt>:
 
-Require the rake tasks from your application's <tt>Rakefile</tt> (only if installed as a gem):
+ gem 'HasRemote', '~> 0.2.0', :require => 'has_remote'
 
- require 'has_remote/tasks'
+And only if you require synchronization, run:
+
+ rails generate has_remote:migration
+ rake db:migrate
+
+==== Rails 2.3
 
-As a plugin; Run:
+Add the following to <tt>environment.rb</tt>:
 
- script/plugin install git://github.com/innovationfactory/has_remote.git
+ config.gem 'HasRemote', :version => '~> 0.1.7', :lib => 'has_remote'
 
 And only if you require synchronization, run:
 
  script/generate has_remote_migration
-
  rake db:migrate
- 
+
 === Links
 
 [RDoc:] http://rdoc.info/projects/innovationfactory/has_remote
@@ -116,7 +120,7 @@ Synchronize all records of one specific model:
 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>updated_remotes</tt> class method in your model to match your host's REST API.
 
-See <tt>HasRemote::Synchronizable</tt> for more information.
+See {HasRemote::Synchronizable} for more information.
 
 ==== Rake hr:sync
 
@@ -128,23 +132,22 @@ certain models by using the <tt>MODELS</tt> variable:
 
  rake hr:sync MODELS=Contact,Company
 
-To specify additional parameters to send with the request that fetches updated resources use the PARAMS variable:
+To specify additional parameters to send with the request that fetches updated resources use the <tt>PARAMS</tt> variable:
 
  rake hr:sync PARAMS="since=01-01-2010&limit=25"
 
-(If you've overridden the <tt>updated_remotes</tt> class method on one of your synchronizable models, then note that these parameters are
-passed in as a hash to <tt>updated_remotes</tt> internally.)
+(If you've overridden the {HasRemote::Synchronizable#updated_remotes #updated_remotes} class method on one of your synchronizable models, then note that these parameters are
+passed in as a hash to {HasRemote::Synchronizable#updated_remotes #updated_remotes} internally.)
 
 === Testing
 
-To run the specs of the plugin, from the HasRemote directory run:
- rake spec
-
-(This requires you to have both RSpec and Shoulda installed.)
+Install Bundler and run <tt>bundle install</tt> in order to obtain RSpec and other dependencies.
+To run the specs, from the root folder run:
+ rspec spec
 
 === More information & patches
 
 Questions, requests and patches can be directed to sjoerd.andringa[AT]innovationfactory[DOT]eu.
 
 
-Copyright (c) 2009-2010 Innovation Factory.
+Copyright (c) 2009-2011 Innovation Factory.

data/Rakefile

@@ -1,35 +1,18 @@
 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"]
+  Jeweler::Tasks.new do |gem|
+    gem.name        = "HasRemote"
+    gem.version     = File.read('VERSION').chomp
+    gem.summary     = "Bind a remote ActiveResource object to your local ActiveRecord objects."
+    gem.description = "Bind a remote ActiveResource object to your local ActiveRecord objects, delegate attributes and optionally cache remote attributes locally."
+    gem.email       = "sjoerd.andringa@innovationfactory.eu"
+    gem.homepage    = "http://github.com/innovationfactory/has_remote"
+    gem.authors     = ["Sjoerd Andringa"]
   end
-  Jeweler::GemcutterTasks.new
+  Jeweler::RubygemsDotOrgTasks.new
 rescue LoadError
   puts "Jeweler not available. Install it with: gem install jeweler"
 end

data/TODO

@@ -15,7 +15,7 @@
  <user>
    <id type="integer">1</id>
    <remote site="...">
-	   <id type="integer">1</id>
-	   <name>George Remote</name>
-	 </remote>
+     <id type="integer">1</id>
+     <name>George Remote</name>
+   </remote>
  </user>

data/VERSION

@@ -1 +1 @@
-0.1.7
+0.2.0

data/lib/generators/has_remote/migration_generator.rb

@@ -0,0 +1,20 @@
+require 'rails/generators/active_record/migration'
+
+module HasRemote
+  module Generators
+    class MigrationGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      extend  ActiveRecord::Generators::Migration
+
+      source_root File.join(File.dirname(__FILE__), 'templates')
+
+      desc <<-TXT.squish
+        Creates a migration that will set up the has_remote_synchronizations table. You don't need this
+        if you don't plan on synchronizing cached remote attributes.
+      TXT
+      def create_migration
+        migration_template "create_has_remote_synchronizations.rb", "db/migrate/create_has_remote_synchronizations.rb"
+      end
+    end
+  end
+end

data/lib/has_remote.rb

@@ -1,8 +1,12 @@
-# The main module for the has_remote plugin. Please see README for more information.
+require 'has_remote/synchronizable'
+require 'has_remote/synchronization'
+require 'has_remote/railtie'
+
+# The main module for the has_remote plugin. Please see {file:README.rdoc README} for more information.
 #
 module HasRemote
 
-  def self.included(base) #:nodoc:
+  def self.included(base)
     base.extend ClassMethods
   end
 
@@ -10,13 +14,15 @@ module HasRemote
   #
   def self.models
     # Make sure all models are loaded:
-    Dir[File.join(RAILS_ROOT, 'app', 'models', '*.rb')].each { |f| require_dependency f }
+    if Rails.root
+      Dir[Rails.root.join('app', 'models', '*.rb')].each { |f| require_dependency f }
+    end
 
     @models ||= []
   end
 
   # Updates cached attributes, destroys deleted records and adds new records of all models that have a remote.
-  # Also see HasRemote::Synchronizable.
+  # Also see {HasRemote::Synchronizable}.
   #
   def self.synchronize!
     models.each(&:synchronize!)
@@ -24,20 +30,10 @@ module HasRemote
 
   module ClassMethods
 
-    # Gives your local ActiveRecord model a remote proxy (ActiveResource::Base),
-    # which enables you to look for certain attributes remotely.
-    #
-    # ==== Options
+    # Binds your <tt>ActiveRecord</tt> objects to a remote <tt>ActiveResource</tt> resource,
+    # and enables you to look for certain attributes remotely.
     #
-    # [: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
+    # ==== Usage:
     #
     #  class User < ActiveRecord::Base
     #    has_remote :site => 'http://people.local'
@@ -51,7 +47,7 @@ module HasRemote
     #  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
+    # has_remote also takes a block which is passed in a {Config} object which can be used to specify
     # remote attributes:
     #
     #  class User < ActiveRecord::Base
@@ -65,9 +61,17 @@ module HasRemote
     #  User.find(1).username
     #  # => "User name from remote server"
     #
+    # @option options [Symbol, String] :foreign_key (:remote_id) The name of the column used to store the id of the remote resource..
+    # @option options [Symbol, String] :remote_primary_key (:id) The name of the remote resource's primary key.
+    # @option options [String] :through Optional custom <tt>ActiveResource</tt> class name to use for the proxy. If not set, a default class called
+    #                          <tt>Remote</tt> will be created dynamically, namespaced inside the current model. *Note* that any <tt>ActiveResource</tt>
+    #                          configuration options will still be applied to this class.
+    # @option options Other All other options you pass in will be used to configure the <tt>ActiveResource</tt> model, you can use any setting for {http://api.rubyonrails.org/classes/ActiveResource/Base.html ActiveResource::Base}, such as <tt>:site</tt>, <tt>:user</tt> and <tt>:password</tt>.
+    # @yieldparam [Config] remote Configure attributes to be delegated or a custom finder.
+    #
     def has_remote(options, &block)
       unless options[:through] || self.const_defined?("Remote")
-        self.const_set("Remote", ActiveResource::Base.clone)
+        self.const_set("Remote", Class.new(ActiveResource::Base))
       end
 
       @remote_class = options[:through] ? options.delete(:through).constantize : self::Remote
@@ -117,12 +121,10 @@ module HasRemote
 
   module InstanceMethods
 
-    # Returns the remote proxy for this record as an <tt>ActiveResource::Base</tt> object. Returns nil
-    # if foreign key is nil.
+    # Returns the remote proxy for this record as an <tt>ActiveResource::Base</tt> object. Returns <tt>nil</tt>
+    # if foreign key is <tt>nil</tt>.
     #
-    # *Arguments*
-    #
-    # - <tt>force_reload</tt>:  Forces a reload from the remote server if set to true. Defaults to false.
+    # @param [Boolean] force_reload Forces a reload from the remote server if set to <tt>true</tt>.
     #
     def remote(force_reload = false)
       if force_reload || @remote.nil?
@@ -134,6 +136,8 @@ module HasRemote
 
     # Checks whether a remote proxy exists.
     #
+    # @return [Boolean]
+    #
     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
@@ -143,6 +147,8 @@ module HasRemote
 
     # Synchronizes all locally cached remote attributes to this object and saves the object.
     #
+    # @raise [ActiveRecord::RecordInvalid]
+    #
     def update_cached_attributes!
       update_cached_attributes
       save!
@@ -151,7 +157,7 @@ module HasRemote
     # 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.
+    # set to <tt>nil</tt>.
     #
     def update_cached_attributes
       unless self.skip_update_cache || self.class.cached_attributes.empty?
@@ -165,20 +171,19 @@ module HasRemote
 
   end
 
+  # The block argument for {HasRemote::ClassMethods#has_remote} is an instance of this class.
+  # It can be used to configure HasRemote's behaviour for a model.
+  #
   class Config
+
+    # @private
     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*
+    # ==== Example:
     #
     #  class User < ActiveRecord::Base
     #    has_remote :site => '...' do |remote|
@@ -187,6 +192,11 @@ module HasRemote
     #    end
     #  end
     #
+    # @param [String, Symbol] attr_name The name of the attribute you want to delegate to the remote.
+    # @option options [Boolean] :local_cache (false) If set to <tt>true</tt> the attribute will also be saved locally. See {file:README.rdoc README} for more information
+    #                 about caching and synchronization.
+    # @option options [Symbol, String] :as Optionally map the remote attribute to this name.
+    #
     def attribute(attr_name, options = {})
       method_name = options[:as] || attr_name
 
@@ -212,12 +222,12 @@ module HasRemote
     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.
+    # 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*
+    # By default the following finder is used:
+    #  MyModel.remote_class.find(id)
     #
+    # ==== Example:
     #  class User < ActiveRecord::Base
     #    has_remote :site => "..." do |remote|
     #      remote.finder do |id|
@@ -231,5 +241,4 @@ module HasRemote
     end
 
   end
-
 end