kelredd-resourceful 0.7.20 → 0.7.21

data/README.rdoc

@@ -2,27 +2,31 @@
 
 == Description
 
-A ruby gem to abstract web resource handling.  You configure the server, resource format, etc... and
-the gem will provide interactions with that resource in a restful manner, with data returned in a 
-de-serialized object format.
+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)
+ 
+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)
 
 == Installation
 
-    sudo gem install kelredd-resourceful --source http://gems.github.com
+    sudo gem install kelredd-resourceful --source http://gemcutter.org
     
 == Dependencies
 
  * nokogiri (xml resource format handling)
  * json (json resource format handling)
- * rest_client (rest web resource access)
+ * rest_client (restful web resource access agent)
+ * mechanize (more raw web resource access agent; access secured resources)
  * log4r (for resource interaction logging)
- * kelredd-useful (some nice ruby helpers)
 
-== Usage
+== Basic Usage
 
     # Single host resource handling
     require 'resourceful'
@@ -31,11 +35,49 @@ The supported formats are:
     Resourceful::Resource.get '/widgets', :format => 'json'  # specify explicit format
     Resourceful::Resource.get '/widgets.json'                # or, imply format from resource request
     
-    # TODO: extend to create Resource instances that have per instance host, path, format settings
+== Defining Models
+
+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
+ 
+== Cacheing
+
+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.
+ 
+=== 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
+ 
+== Logging
+
+Resourceful provides resource agent logging for you by default.  Log information is written to the console for confirmation of resource access.  In addition, you can specify a file to log to by implementing a block that returns the path of a file to log to, such as:
+
+    @mechanize ||= Resourceful::Agent::Mechanize.new(:host => @host, :agent_alias => @agent_alias, :verbose => @verbose) do
+      @log_file ? File.expand_path(@log_file) : nil
+    end
+
+== 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)
     
-== Testing
-A suite of cucumber features are available for you to run as an acceptance test.  You should look to the features 
-for additional documentation and usage scenarios.  To run the features:
+== 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:
 
     # make sure you have these gems
     $ sudo gem install cucumber

data/Rakefile

@@ -24,7 +24,6 @@ spec = Gem::Specification.new do |s|
   s.add_dependency('rest-client')
   s.add_dependency('mechanize')
   s.add_dependency('log4r')
-  s.add_dependency('kelredd-useful')
 end
 
 Rake::GemPackageTask.new(spec) do |pkg|

data/lib/resourceful/agent/base.rb

@@ -5,14 +5,14 @@ module Resourceful
   module Agent
     class Base
       
-      attr_reader :logger, :cache
+      attr_reader :logger, :cache, :expiration, :log_prefix
 
-      ATTRS = [:host, :user, :password]
+      ATTRS = [:host, :user, :password, :expiration, :log_prefix]
       ATTRS.each { |a| attr_reader a }
       
       def initialize(args={})
         ATTRS.each { |a| instance_variable_set("@#{a.to_s}", args.delete(a)) }
-        @cache = Resourceful::Resource::Cache.new
+        @cache = Resourceful::Resource::Cache.new @expiration
         @logger = Log4r::Logger.new('[Resourceful]')
         @logger.add(Log4r::StdoutOutputter.new('console'))
       end
@@ -61,7 +61,7 @@ module Resourceful
       end
       
       def log(msg, level = :info) # :nodoc:
-        @logger.send(level.to_s, msg) if msg
+        @logger.send(level.to_s, "#{"[#{@log_prefix.to_s}]" if @log_prefix} #{msg}") if msg
       end
       
       def log=(file)

data/lib/resourceful/model/base.rb

@@ -105,7 +105,9 @@ module Resourceful
           fetch_attribute(clean_name, config, content_method)
         end
         # method to read the attribute value (intended to be overridden when necessary)
-        define_method(name) do
+        define_method(name) do |*args|
+          reload = args.first || false
+          instance_variable_set("@#{clean_name}", nil) if reload
           fetch_attribute(clean_name, config, content_method)
         end
         # method to write the attribute value

data/lib/resourceful/resource/cache.rb

@@ -2,15 +2,16 @@ module Resourceful
   module Resource
     class Cache
 
-      attr_reader :store
+      attr_reader :store, :expiration
       
-      EXPIRY_SECS = 30
+      EXPIRY_SECS = 60
       
       def self.key(host, verb, resource)
         "#{host}_#{verb}_#{resource}"
       end
 
-      def initialize
+      def initialize(expiration=EXPIRY_SECS)
+        @expiration = (expiration && expiration.kind_of?(::Fixnum)) ? expiration : EXPIRY_SECS
         @store = {}
       end
 
@@ -28,7 +29,7 @@ module Resourceful
       end
       
       def write(key, value)
-        @store[key] = {:value => value, :expires => Time.now.to_i + EXPIRY_SECS}
+        @store[key] = {:value => value, :expires => Time.now.to_i + @expiration}
         value
       end
       

data/lib/resourceful/version.rb

@@ -3,7 +3,7 @@ module Resourceful
     
     MAJOR = 0
     MINOR = 7
-    TINY  = 20
+    TINY  = 21
     
     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.20
+  version: 0.7.21
 platform: ruby
 authors: 
 - Kelly Redding
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-10-01 00:00:00 -05:00
+date: 2009-10-03 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -62,16 +62,6 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: "0"
     version: 
-- !ruby/object:Gem::Dependency 
-  name: kelredd-useful
-  type: :runtime
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
-    version: 
 description: 
 email: kelly@kelredd.com
 executables: []