kelredd-resourceful 0.1.1

data/README.rdoc

@@ -0,0 +1,69 @@
+= Resourceful
+
+== 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.
+
+The supported formats are:
+ * JSON (objects returned as Ruby Hash)
+ * XML (objects returned as Nokogiri Xml object)
+
+== Installation
+
+    sudo gem install kelredd-resourceful --source http://gems.github.com
+    
+== Dependencies
+
+ * nokogiri (xml resource format handling)
+ * json (json resource format handling)
+ * rest_client (rest web resource access)
+ * log4r (for resource interaction logging)
+ * kelredd-useful (some nice ruby helpers)
+
+== Usage
+
+    # Single host resource handling
+    require 'resourceful'
+    Resourceful::Resource.configure :host => 'localhost:3000'
+    Resourceful::Resource::Cache.clear
+    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
+    
+== 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:
+
+    # make sure you have the cucumber gem
+    $ sudo gem install cucumber
+    # change to the resourceful gem installed location
+    $ cd /opt/local/lib/ruby/gems/x.x/gems/kelredd-resourceful-xxx
+    $ rake features
+
+== License
+
+Copyright (c) 2009 Kelly Redding
+
+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/Rakefile

@@ -0,0 +1,51 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rake/testtask'
+
+require 'lib/resourceful/version'
+
+task :default => :test
+
+spec = Gem::Specification.new do |s|
+  s.name             = 'resourceful'
+  s.version          = Resourceful::Version.to_s
+  s.has_rdoc         = true
+  s.extra_rdoc_files = %w(README.rdoc)
+  s.rdoc_options     = %w(--main README.rdoc)
+  s.summary          = "A ruby gem to abstract web resource handling."
+  s.author           = 'Kelly Redding'
+  s.email            = 'kelly@kelredd.com'
+  s.homepage         = ''
+  s.files            = %w(README.rdoc Rakefile) + Dir.glob("{features,lib,test}/**/*")
+  # s.executables    = ['resourceful']
+  
+  s.add_dependency('nokogiri')
+  s.add_dependency('json')
+  s.add_dependency('rest_client')
+  s.add_dependency('log4r')
+  s.add_dependency('kelredd-useful')
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+desc 'Generate the gemspec to serve this Gem from Github'
+task :github do
+  file = File.dirname(__FILE__) + "/#{spec.name}.gemspec"
+  File.open(file, 'w') {|f| f << spec.to_ruby }
+  puts "Created gemspec: #{file}"
+end
+
+require 'cucumber'
+require 'cucumber/rake/task'
+
+Cucumber::Rake::Task.new(:features) do |t|
+  t.cucumber_opts = "features --format pretty" 
+end

data/features/config_resource.feature

@@ -0,0 +1,29 @@
+Feature: Config Resource
+  In order to consume rest based resources
+  As an user
+  I want to configure Resourceful for a particular resource format and host
+  
+  Scenario: JSON Format definition
+    Given I want to use the json resource format
+    Then the format should be .json
+  
+  Scenario: XML Format definition
+    Given I want to use the xml resource format
+    Then the format should be .xml
+  
+  Scenario: Host not configured
+    Given I have no host server configured
+    Then resourceful should complain about a configuration error
+
+  Scenario: Host configured
+    Given I have a configured resource host
+    Then the host should be set
+
+  Scenario: Resource logger
+    Given I have a configured resource host set to log
+    Then verify the log settings
+
+  Scenario: Resource logging
+    Given I have a configured resource host set to log
+    When I get a json formatted resource
+    Then the set log file should exist

data/features/get_resource.feature

@@ -0,0 +1,34 @@
+Feature: Get Resource
+  In order to consume rest based resources
+  As an object
+  I want to get data from a web resource as a formatted object
+  
+  Scenario: Get JSON resource
+    Given I have a configured resource host
+    When I get a json formatted resource
+    Then the result should be a hash object
+    
+  Scenario: Get XML resource
+    Given I have a configured resource host
+    When I get an xml formatted resource
+    Then the result should be an xml object
+    
+  Scenario: Get an implicit format JSON resource
+    Given I have a configured resource host
+    When I get a json formatted implicitly resource
+    Then the result should be a hash object
+    
+  Scenario: Get an implicit format XML resource
+    Given I have a configured resource host
+    When I get an xml formatted implicitly resource
+    Then the result should be an xml object
+    
+  Scenario: Get resource with format not supported
+    Given I have a configured resource host
+    When I get an poop formatted resource
+    Then resourceful should complain about a format error
+    
+  Scenario: Get non existent resource
+    Given I have a configured resource host
+    When I get a resource that does not exist
+    Then resourceful should complain about the resource not being found

data/features/step_definitions/resource_config_steps.rb

@@ -0,0 +1,23 @@
+Then /^the format should be \.(.+)$/ do |format|
+  assert_equal @format.to_s, format
+end
+
+Then /^the host should be set$/ do
+  assert_equal Resourceful::Resource.host, RESOURCE_CONFIG[:host]
+end
+
+Then /^resourceful should complain about a configuration error$/ do
+  assert_raise Resourceful::Exceptions::ConfigurationError do
+    Resourceful::Resource::Base.get RESOURCE_CONFIG[:resource], :format => 'json', :params => RESOURCE_CONFIG[:params]
+  end
+end
+
+Then /^verify the log settings$/ do
+  assert_equal Resourceful::Resource.logger.outputters.detect{|out| out.respond_to?('filename')}.filename, RESOURCE_CONFIG[:log]
+end
+
+Then /^the set log file should exist$/ do
+  log_file = File.expand_path(RESOURCE_CONFIG[:log])  
+  assert File.exists?(log_file)
+  FileUtils.rm(log_file) if File.exists?(log_file)
+end

data/features/step_definitions/resource_get_steps.rb

@@ -0,0 +1,37 @@
+When /^I get a[n]* (.+) formatted resource$/ do |format|
+  @result = ResourcefulFeature::Helpers.safe_run_get do
+    Resourceful::Resource::Base.get RESOURCE_CONFIG[:resource], :format => format, :params => RESOURCE_CONFIG[:params]
+  end
+end
+
+When /^I get a[n]* (.+) formatted implicitly resource$/ do |format|
+  @result = ResourcefulFeature::Helpers.safe_run_get do
+    Resourceful::Resource::Base.get RESOURCE_CONFIG[:resource]+".#{format}", :params => RESOURCE_CONFIG[:params]
+  end
+end
+
+When /^I get a resource that does not exist$/ do
+  @result = ResourcefulFeature::Helpers.safe_run_get do
+    Resourceful::Resource::Base.get '/unknown', :format => 'xml', :params => RESOURCE_CONFIG[:params]
+  end
+end
+
+Then /^the result should be a hash object$/ do
+  assert_kind_of Hash, @result.first
+end
+
+Then /^the result should be an xml object$/ do
+  assert_kind_of Nokogiri::XML::Document, @result
+end
+
+Then /^resourceful should complain about a format error$/ do
+  assert @result
+  assert_kind_of Resourceful::Exceptions::FormatError, @result
+  assert @result.message.length > 0
+end
+
+Then /^resourceful should complain about the resource not being found$/ do
+  assert @result
+  assert_kind_of RestClient::ResourceNotFound, @result
+  assert @result.message.length > 0
+end

data/features/step_definitions/support/env.rb

@@ -0,0 +1,11 @@
+require 'test/unit/assertions'
+World(Test::Unit::Assertions)
+
+RESOURCE_CONFIG = {
+  :host => 'twitter.com',
+  :resource => '/statuses/public_timeline',
+  :params => {},
+  :log => "./test.log"
+}
+
+require File.dirname(__FILE__) + '/../../../lib/resourceful'

data/features/step_definitions/support/helpers.rb

@@ -0,0 +1,13 @@
+module ResourcefulFeature
+  module Helpers
+    
+    def self.safe_run_get
+      begin
+        yield
+      rescue Exception => err
+        err
+      end
+    end
+
+  end
+end

data/features/step_definitions/support/resources.rb

@@ -0,0 +1,19 @@
+Given /^I want to use the (.+) resource format$/ do |format|
+  @format = Resourceful::Resource::Format.get(format)
+end
+
+Given /^I have no host server configured$/ do
+  Resourceful::Resource::Base.configure
+end
+
+Given /^I have a configured resource host$/ do
+  Resourceful::Resource::Base.configure(:host => RESOURCE_CONFIG[:host])
+end
+
+Given /^I have a configured resource host set to log$/ do
+  log_file = File.expand_path(RESOURCE_CONFIG[:log])
+  FileUtils.rm(log_file) if File.exists?(log_file)
+  Resourceful::Resource::Base.configure(:host => RESOURCE_CONFIG[:host]) {
+    RESOURCE_CONFIG[:log]
+  }
+end

data/lib/resourceful/exceptions.rb

@@ -0,0 +1,11 @@
+module Resourceful
+  module Exceptions
+  
+    class ConfigurationError < ::StandardError
+    end
+    
+    class FormatError < ::StandardError
+    end
+    
+  end
+end

data/lib/resourceful/resource/base.rb

@@ -0,0 +1,84 @@
+require 'rest_client'
+require 'log4r'
+require File.join(File.dirname(__FILE__), 'cache.rb')
+require File.join(File.dirname(__FILE__), 'format.rb')
+require File.join(File.dirname(__FILE__), '..', 'exceptions.rb')
+
+module Resourceful
+  module Resource
+    class Base
+      
+      @@host = nil
+      @@logger = nil
+      
+      def self.configure(opts={})
+        Resourceful::Resource::Cache.clear
+        @@logger = Log4r::Logger.new('Resourceful Base')
+        @@logger.add(Log4r::StdoutOutputter.new('console'))
+        if block_given?
+          log_file = yield
+          @@logger.add(Log4r::FileOutputter.new('fileOutputter', :filename => log_file, :trunc => false, :formatter => Log4r::PatternFormatter.new(:pattern => "[%l] %d :: %m"))) rescue nil
+          RestClient.log = log_file
+        end
+        @@host = opts[:host]
+      end
+      
+      def self.host
+        @@host
+      end
+      
+      def self.logger
+        @@logger
+      end
+
+      # KDR: returns the resource specified in hash form
+      def self.get(path, opts={}, force=false)
+        path, opts = check_config(path, opts)
+        @@rest_client ||= ::RestClient::Resource.new("http://#{@@host}")
+        format = Resourceful::Resource::Format.get(opts[:format])
+        request_summary = summary('get', path, format, opts[:params])
+        cache = Resourceful::Resource::Cache.new(@@host, 'get', path, format, opts[:params])
+
+        if force || (resp = cache.read).nil?
+          log "Resource call: #{request_summary}"
+          resp = cache.write(@@rest_client[rest_path(path, format, opts[:params])].get)
+        else
+          log "Resource call: [CACHE] #{request_summary}"
+        end
+        format.build(resp)
+      end
+
+      private
+
+      def self.summary(verb, path, format, params) # :nodoc:
+        "#{verb.upcase} #{@@rest_client.url}#{rest_path(path, format, params)}"
+      end
+      
+      def self.rest_path(path, format, params) # :nodoc:
+        "#{path}.#{format}#{params.to_http_query_str unless params.empty?}"
+      end
+
+      def self.check_config(path, opts)
+        raise Resourceful::Exceptions::ConfigurationError, "please configure a host for Resourceful resources" unless @@host
+        if path =~ /^(.+)\.(.+)$/
+          path = $1
+          opts[:format] ||= $2
+        end
+        opts[:format] ||= Resourceful::Resource::Json.to_s
+        opts[:params] ||= {}
+        [path, opts]
+      end
+      
+      def self.log(msg, level = :info) # :nodoc:
+        if(msg)
+          if @@logger && @@logger.respond_to?(level)
+            @@logger.send(level.to_s, msg) 
+          else
+            puts "** [#{level.to_s.upcase}]: #{msg}"
+          end
+        end
+      end 
+
+    end
+  end
+end

data/lib/resourceful/resource/cache.rb

@@ -0,0 +1,47 @@
+module Resourceful
+  module Resource
+    class Cache
+
+      @@cache = {}
+
+      def self.clear(key=nil)
+        if key
+          @@cache[key] = nil
+        else
+          @@cache = {}
+        end
+      end
+      
+      def self.read(key)
+        @@cache[key]
+      end
+      
+      def self.write(key, value)
+        @@cache[key] = value
+      end
+
+      def self.key(server, verb, path, format, params)
+        "#{server}_#{verb}_#{path}_#{format.to_s}_#{params.to_s}"
+      end
+      
+      attr_reader :key
+      
+      def initialize(server, verb, path, format, params)
+        @key = self.class.key(server, verb, path, format, params)
+      end
+      
+      def read
+        self.class.read(@key)
+      end
+      
+      def write(value)
+        self.class.write(@key, value)
+      end
+      
+      def clear
+        self.class.clear(@key)
+      end
+
+    end
+  end
+end

data/lib/resourceful/resource/format.rb

@@ -0,0 +1,65 @@
+require 'nokogiri'
+require 'json'
+
+module Resourceful
+  module Resource
+    class Format
+      
+      SUPPORTED = ['json', 'xml']
+      
+      def self.get(format)
+        raise Resourceful::Exceptions::FormatError, "the format '#{format}' is not supported" unless SUPPORTED.include?(format.to_s)
+        self.send(format)
+      end
+      
+      def self.json
+        Resourceful::Resource::Json
+      end
+        
+      def self.xml
+        Resourceful::Resource::Xml
+      end
+      
+      def self.to_s
+        raise 'method not implemented by this format'
+      end
+        
+      def self.build(str)
+        raise 'method not implemented by this format'
+      end
+        
+    end
+  end
+end
+
+module Resourceful
+  module Resource
+    class Json < Resourceful::Resource::Format
+      
+      def self.to_s
+        "json"
+      end
+        
+      def self.build(json_str)
+        Hash.from_json(json_str.to_s)
+      end
+        
+    end
+  end
+end
+
+module Resourceful
+  module Resource
+    class Xml < Resourceful::Resource::Format
+      
+      def self.to_s
+        "xml"
+      end
+        
+      def self.build(xml_str)
+        Nokogiri::XML(xml_str.to_s)
+      end
+        
+    end
+  end
+end

data/lib/resourceful/resource.rb

@@ -0,0 +1,25 @@
+Dir[File.join(File.dirname(__FILE__), "resource" ,"*.rb")].each do |file|
+  require file
+end
+
+module Resourceful
+  module Resource
+    
+    def self.configure(opts={}, &block)
+      Resourceful::Resource::Base.configure(opts, &block)
+    end
+
+    def self.get(resource, opts={}, force=false)
+      Resourceful::Resource::Base.get(resource, opts, force)
+    end
+
+    def self.host
+      Resourceful::Resource::Base.host
+    end
+
+    def self.logger
+      Resourceful::Resource::Base.logger
+    end
+
+  end
+end

data/lib/resourceful/version.rb

@@ -0,0 +1,13 @@
+module Resourceful
+  module Version
+    
+    MAJOR = 0
+    MINOR = 1
+    TINY  = 1
+    
+    def self.to_s # :nodoc:
+      [MAJOR, MINOR, TINY].join('.')
+    end
+    
+  end
+end

data/lib/resourceful.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'nokogiri'
+require 'json'
+require 'rest_client'
+require 'log4r'
+require 'useful/ruby_extensions'
+
+require File.join(File.dirname(__FILE__), 'resourceful', 'exceptions.rb')
+require File.join(File.dirname(__FILE__), 'resourceful', 'resource.rb')
+#require File.join(File.dirname(__FILE__), 'resourceful', 'resource.rb')

data/test/test_helper.rb

@@ -0,0 +1,9 @@
+# http://sneaq.net/textmate-wtf
+$:.reject! { |e| e.include? 'TextMate' }
+
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+
+require File.dirname(__FILE__) + '/../lib/resourceful'
+

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification 
+name: kelredd-resourceful
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+platform: ruby
+authors: 
+- Kelly Redding
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-07-21 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: nokogiri
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: rest_client
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: log4r
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !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: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- Rakefile
+- features/config_resource.feature
+- features/get_resource.feature
+- features/step_definitions
+- features/step_definitions/resource_config_steps.rb
+- features/step_definitions/resource_get_steps.rb
+- features/step_definitions/support
+- features/step_definitions/support/env.rb
+- features/step_definitions/support/helpers.rb
+- features/step_definitions/support/resources.rb
+- lib/resourceful
+- lib/resourceful/exceptions.rb
+- lib/resourceful/resource
+- lib/resourceful/resource/base.rb
+- lib/resourceful/resource/cache.rb
+- lib/resourceful/resource/format.rb
+- lib/resourceful/resource.rb
+- lib/resourceful/version.rb
+- lib/resourceful.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: ""
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+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.2.0
+signing_key: 
+specification_version: 2
+summary: A ruby gem to abstract web resource handling.
+test_files: []
+