kelredd-resourceful 0.7.21 → 0.7.22

data/README.rdoc

@@ -7,12 +7,12 @@ A ruby gem to abstract web resource handling.
 The key to resourceful is being able to interact with web resources using custom defined objects instead of the raw data.  Unlike ActiveResource, Resourceful needs no rigid restful API backing its models.  All you need is data in either JSON or XML (or HTML), and be able to creatively define models from that data.
 
 The supported formats are:
- * JSON (objects returned as Ruby Hash)
- * XML (objects returned as Nokogiri Xml object)
+* JSON (objects returned as Ruby Hash)
+* XML (objects returned as Nokogiri Xml object)
  
 Resourceful uses agents to fetch and push data to and from web resources.  Supported agents are:
- * rest_client: great for interacting with Restful resources
- * mechanize: great for interacting with raw resources, or secured resources (and for screen scraping raw html)
+* rest_client: great for interacting with Restful resources
+* mechanize: great for interacting with raw resources, or secured resources (and for screen scraping raw html)
 
 == Installation
 
@@ -20,11 +20,11 @@ Resourceful uses agents to fetch and push data to and from web resources.  Suppo
     
 == Dependencies
 
- * nokogiri (xml resource format handling)
- * json (json resource format handling)
- * rest_client (restful web resource access agent)
- * mechanize (more raw web resource access agent; access secured resources)
- * log4r (for resource interaction logging)
+* nokogiri (xml resource format handling)
+* json (json resource format handling)
+* rest_client (restful web resource access agent)
+* mechanize (more raw web resource access agent; access secured resources)
+* log4r (for resource interaction logging)
 
 == Basic Usage
 
@@ -40,25 +40,25 @@ Resourceful uses agents to fetch and push data to and from web resources.  Suppo
 So it's all about the models, right.  So you have this data resource on the web: a JSON API, an XML feed, an old crappy HTML page, a secured page with personal data you want to access.  You start noticing attributes and relationships in this data - it's time to define some models.  Enter resourceful.  Resourceful gives you fancy pants ways to define and test some models, without bothering with all the kruft of accessing those resources via the web.  Check it:
 
 # TODO: show examples of
- * base access stuff
- * defining attributes
- * defining relationships
- * testing the model
+* base access stuff
+* defining attributes
+* defining associations
+* testing the model
  
-== Cacheing
+== Caching
 
 Resourceful provides resource caching by default, both at the model level and at the agent level.
 
 === Model Caching
 
 Model caching refers to using the instance of the model to store attribute and association values.  Resourceful, by default, caches all attribute values and associations in the model instance.  Both attribute values and association values can be "reloaded" by passing true as a single parameter to the attribute or association method.  Please note:
- * For attribute values, "reloading" simply means parsing the value from the existing raw agent data.  The resource is not fetched via the web for attribute reloading.
- * For associations, "reloading" means calling out for the resource and fetching it from the web.  This bypasses any agent caching and forces the resource data to be downloaded.
+* For attribute values, "reloading" simply means parsing the value from the existing raw agent data.  The resource is not fetched via the web for attribute reloading.
+* For associations, "reloading" means calling out for the resource and fetching it from the web.  This bypasses any agent caching and forces the resource data to be downloaded.
  
 === Agent Caching
 
 Agent caching refers to using a built in cache to store web resource responses for future access.  Resourceful, by default, caches all web requests made via the agents.  Resource responses are cached in memory, based on a unique key, and expire, by default, after 60 seconds.  Custom expiration periods can be specified.  This improves performance when repetitively accessing the same resource, while ensuring the resource does not become stale.  Caching can be bypassed on any request by forcing data download using the :force => true option in agent or model data access methods.
- * Note: all cached requests will be prepended with "[CACHE]" in resource agent logs
+* Note: all cached requests will be prepended with "[CACHE]" in resource agent logs
  
 == Logging
 
@@ -71,10 +71,12 @@ Resourceful provides resource agent logging for you by default.  Log information
 == Examples
 
 # TODO: add in examples:
-  * Restful JSON / XML resources
-  * Resourceful external associations
-  * Using associations with non resourceful ruby class (such as an ActiveRecord model)
-  * Screen scraping example (using mechanize to access a secured resource)
+* Screen scraping example (using mechanize to access a secured resource)
+* Restful JSON / XML resources
+* Resourceful external associations
+* Resourceful embedded associations
+* Using associations with non resourceful ruby class (such as an ActiveRecord model)
+* Association eager loading
     
 == Testing the Resourceful gem
 A suite of cucumber features are available for you to run as acceptance tests.  You should look to the features for additional documentation and usage scenarios.  To run the features:

data/lib/resourceful/extensions.rb

@@ -38,7 +38,7 @@ module Resourceful
         end
       end
 
-      unless "".respond_to?(:to_datetime) 
+      unless "".respond_to?(:to_date) 
         def to_date
           ::Date.civil(*::Date._parse(self, false).values_at(:year, :mon, :mday).map { |arg| arg || 0 }) rescue nil
         end

data/lib/resourceful/model/activerecord_associations.rb

@@ -6,10 +6,6 @@ module Resourceful
 
         protected
         
-        def has_one_resourceful(name, config={})
-          has_many(name, config).first
-        end
-
         def has_many_resourceful(name, config={})
           clean_name = Resourceful::Model::Base.cleanup_name(name)
           config ||= {}
@@ -17,18 +13,18 @@ module Resourceful
           class_name = config.delete(:class_name).to_s
           find_method_name = (config.delete(:method) || 'find').to_s
           force = config.delete(:force) || false
+          foreign_key_name = config.delete(:foreign_key) || "#{self.name.demodulize.underscore}_id"
+          foreign_key_method = config.delete(:foreign_key_method) || 'id'
           define_method(name) do |*args|
             reload = args.first || false
-            klass = class_name.resourceful_constantize
-            raise ArgumentError, "has_many_resourceful :class_name '#{class_name}' is not defined" if klass.nil?
-            unless klass.respond_to?(find_method_name)
-              raise NotImplementedError, "has_many_resourceful expects #{klass} to implement a Findable method named '#{find_method_name}'"
-            end
-            fk = config.delete(:foreign_key) || "#{self.class.name.demodulize.underscore}_id"
-            fk_method = config.delete(:foreign_key_method) || 'id'
-            config[fk] = self.send(fk_method)
             if reload || (assoc_val = instance_variable_get("@#{clean_name}")).nil?
-              instance_variable_set("@#{clean_name}", klass.send(find_method_name, :all, config, force))
+              klass = class_name.resourceful_constantize
+              raise ArgumentError, "has_many_resourceful :class_name '#{class_name}' is not defined" if klass.nil?
+              unless klass.respond_to?(find_method_name)
+                raise NotImplementedError, "has_many_resourceful expects #{klass} to implement a Findable method named '#{find_method_name}'"
+              end
+              config[foreign_key_name] = self.send(foreign_key_method)
+              instance_variable_set("@#{clean_name}", klass.send(find_method_name, :all, config, reload || force))
             else
               assoc_val
             end
@@ -40,28 +36,25 @@ module Resourceful
           config ||= {}
           raise ArgumentError, "belongs_to_resourceful requires a :class_name option to be specified" unless config[:class_name]
           class_name = config.delete(:class_name).to_s
-          foreign_key = config.delete(:foreign_key) || "#{clean_name}_id"
           find_method_name = (config.delete(:method) || 'find').to_s
           force = config.delete(:force) || false
+          foreign_key_name = config.delete(:foreign_key_name) || 'id'
+          foreign_key_method = config.delete(:foreign_key) || "#{clean_name}_id"
           define_method(name) do |*args|
             reload = args.first || false
-            klass = class_name.resourceful_constantize
-            raise ArgumentError, "belongs_to_resourceful :class_name '#{class_name}' is not defined" if klass.nil?
-            unless self.respond_to?(foreign_key)
-              raise ArgumentError, "belongs_to_resourceful requires a '#{foreign_key}' method defined to return the foreign_key"
-            end
-            unless klass.respond_to?(find_method_name)
-              raise NotImplementedError, "belongs_to_resourceful expects #{klass} to implement a Findable method named '#{find_method_name}'"
-            end
-            fk = self.send(foreign_key)
-            if fk.nil? || (fk.respond_to?('empty?') && fk.empty?)
-              nil
-            else
-              if reload || (assoc_val = instance_variable_get("@#{clean_name}")).nil?
-                instance_variable_set("@#{clean_name}", klass.send(find_method_name, fk, config, force))
-              else
-                assoc_val
+            if reload || (assoc_val = instance_variable_get("@#{clean_name}")).nil?
+              klass = class_name.resourceful_constantize
+              raise ArgumentError, "belongs_to_resourceful :class_name '#{class_name}' is not defined" if klass.nil?
+              unless self.respond_to?(foreign_key_method)
+                raise ArgumentError, "belongs_to_resourceful requires a '#{foreign_key_method}' method defined to return the foreign_key"
+              end
+              unless klass.respond_to?(find_method_name)
+                raise NotImplementedError, "belongs_to_resourceful expects #{klass} to implement a Findable method named '#{find_method_name}'"
               end
+              fk = self.send(foreign_key_method)
+              instance_variable_set("@#{clean_name}", fk.nil? || (fk.respond_to?('empty?') && fk.empty?) ? nil : klass.send(find_method_name, fk, config, reload || force))
+            else
+              assoc_val
             end
           end
         end

data/lib/resourceful/model/eager_load.rb

@@ -0,0 +1,43 @@
+module Resourceful
+    
+  # The idea here is to take a collection of object instances that have resourceful associations and
+  # => for each association specified
+  #   => get the foreign key name
+  #   => get the foreign key values for each item in the collection
+  #   => grab the data for all the foreign keys in one call
+  #   => build object for each result in data
+  #   => for each item in the collection, set it's association value from built objects
+  def self.eager_load(collection, associations)
+    if (collection.respond_to?('each') && (collection.respond_to?('empty?') && !collection.empty?)) && \
+       (associations.respond_to?('each') && (associations.respond_to?('empty?') && !associations.empty?))
+      klass = collection.first.class
+      associations.each do |association_name|
+        clean_association_name = Resourceful::Model::Base.cleanup_name(association_name.to_s)
+        assoc_data = get_association_data(klass, clean_association_name)
+        assoc_klass = klass.ancestors.include?(Resourceful::Model::Base) ? klass.get_namespaced_klass(assoc_data[:class_name]) : assoc_data[:class_name].resourceful_constantize
+        fk_values = collection.inject([]) {|vals, item| vals << item.send(assoc_data[:foreign_key_method])}
+        fk_results = assoc_klass.send(assoc_data[:find_method_name], :all, {assoc_data[:foreign_key_name] => fk_values.join(',')}, true)
+        collection.each do |item|
+          item_results = fk_results.reject{|result| result.send(assoc_data[:foreign_key_name]) != item.send(assoc_data[:foreign_key_method])}
+          item.instance_variable_set("@#{clean_association_name}", [:belongs_to, :has_one].include?(assoc_data[:type]) ? item_results.first : item_results)
+        end
+      end
+    end
+    collection
+  end
+
+  def self.add_to_associations(klass_name, name, data)
+    @@resourceful_associations ||= {}
+    @@resourceful_associations[klass_name] ||= {}
+    @@resourceful_associations[klass_name][name] = data
+  end
+  def self.get_association_data(klass, name)
+    @@resourceful_associations ||= {}
+    assoc_data = nil
+    klass.ancestors.each do |anc|
+      break if @@resourceful_associations[anc.to_s] && (assoc_data = @@resourceful_associations[anc.to_s][name])
+    end
+    assoc_data
+  end
+
+end

data/lib/resourceful/model/external_associations.rb

@@ -6,10 +6,6 @@ module Resourceful
 
         protected
         
-        def has_one(name, config={})
-          has_many(name, config).first
-        end
-
         def has_many(name, config={})
           clean_name = cleanup_name(name)
           config ||= {}
@@ -17,18 +13,25 @@ module Resourceful
           class_name = config.delete(:class).to_s
           find_method_name = (config.delete(:method) || 'find').to_s
           force = config.delete(:force) || false
+          foreign_key_name = config.delete(:foreign_key) || "#{self.name.demodulize.underscore}_id"
+          foreign_key_method = config.delete(:foreign_key_method) || 'id'
+          Resourceful.add_to_associations(self.name, clean_name, {
+            :type => :has_many,
+            :class_name => class_name,
+            :foreign_key_name => foreign_key_name,
+            :foreign_key_method => foreign_key_method,
+            :find_method_name => find_method_name
+          })
           define_method(name) do |*args|
             reload = args.first || false
-            klass = self.class.get_namespaced_klass(class_name)
-            raise ArgumentError, "has_many :class '#{class_name}' is not defined in any given namespaces" if klass.nil?
-            unless klass.respond_to?(find_method_name)
-              raise NotImplementedError, "has_many expects #{klass} to implement a Findable method named '#{find_method_name}'"
-            end
-            fk = config.delete(:foreign_key) || "#{self.class.name.demodulize.underscore}_id"
-            fk_method = config.delete(:foreign_key_method) || 'id'
-            config[fk] = self.send(fk_method)
             if reload || (assoc_val = instance_variable_get("@#{clean_name}")).nil?
-              instance_variable_set("@#{clean_name}", klass.send(find_method_name, :all, config, force))
+              klass = self.class.get_namespaced_klass(class_name)
+              raise ArgumentError, "has_many :class '#{class_name}' is not defined in any given namespaces" if klass.nil?
+              unless klass.respond_to?(find_method_name)
+                raise NotImplementedError, "has_many expects #{klass} to implement a Findable method named '#{find_method_name}'"
+              end
+              config[foreign_key_name] = self.send(foreign_key_method)
+              instance_variable_set("@#{clean_name}", klass.send(find_method_name, :all, config, reload || force))
             else
               assoc_val
             end
@@ -40,28 +43,32 @@ module Resourceful
           config ||= {}
           raise ArgumentError, "belongs_to requires a :class option to be specified" unless config[:class]
           class_name = config.delete(:class).to_s
-          foreign_key = config.delete(:foreign_key) || "#{clean_name}_id"
           find_method_name = (config.delete(:method) || 'find').to_s
           force = config.delete(:force) || false
+          foreign_key_name = config.delete(:foreign_key_name) || 'id'
+          foreign_key_method = config.delete(:foreign_key) || "#{clean_name}_id"
+          Resourceful.add_to_associations(self.name, clean_name, {
+            :type => :belongs_to,
+            :class_name => class_name,
+            :foreign_key_name => foreign_key_name,
+            :foreign_key_method => foreign_key_method,
+            :find_method_name => find_method_name
+          })
           define_method(name) do |*args|
             reload = args.first || false
-            klass = self.class.get_namespaced_klass(class_name)
-            raise ArgumentError, "belongs_to :class '#{class_name}' is not defined in any given namespaces" if klass.nil?
-            unless self.respond_to?(foreign_key)
-              raise ArgumentError, "belongs_to requires a '#{foreign_key}' method defined to return the foreign_key"
-            end
-            unless klass.respond_to?(find_method_name)
-              raise NotImplementedError, "belongs_to expects #{klass} to implement a Findable method named '#{find_method_name}'"
-            end
-            fk = self.send(foreign_key)
-            if fk.nil? || (fk.respond_to?('empty?') && fk.empty?)
-              nil
-            else
-              if reload || (assoc_val = instance_variable_get("@#{clean_name}")).nil?
-                instance_variable_set("@#{clean_name}", klass.send(find_method_name, fk, config, force))
-              else
-                assoc_val
+            if reload || (assoc_val = instance_variable_get("@#{clean_name}")).nil?
+              klass = self.class.get_namespaced_klass(class_name)
+              raise ArgumentError, "belongs_to :class '#{class_name}' is not defined in any given namespaces" if klass.nil?
+              unless self.respond_to?(foreign_key_method)
+                raise ArgumentError, "belongs_to requires a '#{foreign_key_method}' method defined to return the foreign_key"
+              end
+              unless klass.respond_to?(find_method_name)
+                raise NotImplementedError, "belongs_to expects #{klass} to implement a Findable method named '#{find_method_name}'"
               end
+              fk = self.send(foreign_key_method)
+              instance_variable_set("@#{clean_name}", fk.nil? || (fk.respond_to?('empty?') && fk.empty?) ? nil : klass.send(find_method_name, fk, config, reload || force))
+            else
+              assoc_val
             end
           end
         end

data/lib/resourceful/resource/cache.rb

@@ -1,5 +1,11 @@
 module Resourceful
   module Resource
+    
+    # The idea here is to put Resourceful into an eager loading "mode" while yielding to a block
+    # => while in this mode, resourceful models will try to load and cache data in batches
+    #def self.eager_load
+    #  @@
+    #end
     class Cache
 
       attr_reader :store, :expiration

data/lib/resourceful/shoulda/test_unit.rb

@@ -52,10 +52,11 @@ module Resourceful
         should_have_instance_methods clean_name
         should_have_resourceful_association_collection(name, opts)
       end
-      
-      
-      
-      # Helpers
+    
+
+
+
+      private  # Helpers ***************************************
       
       def should_have_resourceful_typed_attribute(name, type)
         if type

data/lib/resourceful/version.rb

@@ -3,7 +3,7 @@ module Resourceful
     
     MAJOR = 0
     MINOR = 7
-    TINY  = 21
+    TINY  = 22
     
     def self.to_s # :nodoc:
       [MAJOR, MINOR, TINY].join('.')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: kelredd-resourceful
 version: !ruby/object:Gem::Version 
-  version: 0.7.21
+  version: 0.7.22
 platform: ruby
 authors: 
 - Kelly Redding
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-10-03 00:00:00 -05:00
+date: 2009-10-06 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -82,6 +82,7 @@ files:
 - lib/resourceful/model/activerecord_associations.rb
 - lib/resourceful/model/attribute_types.rb
 - lib/resourceful/model/base.rb
+- lib/resourceful/model/eager_load.rb
 - lib/resourceful/model/embedded_associations.rb
 - lib/resourceful/model/external_associations.rb
 - lib/resourceful/model/findable.rb