voorhees 0.2.0

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Richard Livsey
+
+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/README.markdown

@@ -0,0 +1,240 @@
+# Voorhees
+
+## Design goals
+
+* Be as fast as possible
+* Be simple, yet configurable
+* Include just what you need
+* Don't stomp on object hierarcy (it's a mixin)
+* Lazy load only the objects you need, when you need them
+
+## Example usage
+
+    class User
+      include Voorhees::Resource
+      
+      json_service :list, :path => "/users/find.json"
+    
+      def messages
+        json_request(:class => Message) do |r|
+          r.path = "/#{self.id}/messages.json"
+        end
+      end
+    end
+    
+    users = User.list(:page => 2)
+    
+    user = users[0]
+    user.json_attributes      => [:id, :login, :email]
+    user.raw_json             => {:id => 1, :login => 'test', :email => 'bob@example.com'}
+    user.login                => 'test'
+    user.messages             => [Message, Message, Message, ...]
+
+See [/examples/](master/examples/) directory for more.
+
+## A bit more in-depth
+
+### Configuration
+
+Setup global configuration for requests with Voorhees::Config
+These can all be overridden on individual requests/services
+
+    Voorhees::Config.setup do |c|
+      c[:base_uri]  = "http://api.example.com/json"
+      c[:defaults]  = {:api_version => 2}
+      c[:timeout]   = 10
+      c[:retries]   = 3
+    end
+
+#### Global options
+
+* logger: set a logger to use for debug messages, defaults to Logger.new(STDOUT) or RAILS_DEFAULT_LOGGER if it's defined
+
+#### Request global options
+
+These can be set in the global config and overridden on individual services/requests
+
+* base_uri: Prepend all paths with this, usually the domain of the service
+* defaults: A hash of default parameters
+* http_method: The Net::HTTP method to use. One of Net::HTTP::Get (default), Net::HTTP::Post, Net::HTTP::Put or Net::HTTP::Delete 
+* retries: Number of times to retry if it fails to load data from the service
+* timeout: Number of seconds to wait for the service to send data
+
+#### Request specific options
+
+These cannot be globally set and can only be defined on individual services/requests
+
+* hierarchy: Define the class hierarchy for nested data - see below for info
+* parameters: Hash of data to send along with the request, overrides any defaults
+* path: Path to the service. Can be relative if you have a base_uri set.
+* required: Array of required parameters. Raises a Voorhees::ParameterMissingError if a required parameter is not set.
+
+### Timeouts and Retries
+
+As well as setting the open_timeout/read_timeout of Net::HTTP, we also wrap each request in a timeout check.
+
+If [SystemTimer](http://ph7spot.com/articles/system_timer) is installed it will use this, otherwise it falls back on the Timeout library.
+
+If the request fails with a Timeout::Error, or a Errno::ECONNREFUSED, we attept the request again upto the number of retries specified.
+
+For Errno::ECONNREFUSED errors, we also sleep for 1 second to give the service a chance to wake up.
+
+### Services and Requests
+
+There are 3 ways to communicate with the service.
+
+#### json_service
+
+This sets up a class method
+
+    class User
+      include Voorhees::Resource
+      json_service :list, :path => "/users.json"
+    end
+
+    User.list(:page => 3)   =>  [User, User, User, ...] 
+
+By default it assumes you're getting items of the same class, you can override this like so:
+    
+    json_service :list, :path   => "/users.json",
+                        :class  => OtherClass
+
+#### json_request
+
+This is used in instance methods:
+
+    class User
+      include Voorhees::Resource
+      
+      def friends
+        json_request do |r|
+          r.path => "/friends.json"
+          r.parameters => {:user_id => self.id}
+        end
+      end
+    end
+
+    User.new.friends(:limit => 2)  => [User, User]
+
+Like json_service, by default it assumes you're getting items of the same class, you can override this like so:
+
+    def messages
+      json_request(:class => Message) do |r|
+        r.path        = "/messages.json"
+        r.parameters  = {:user_id => self.id}        
+      end
+    end
+
+    User.new.messages  => [Message, Message, ...]
+
+By default a json_request call will convert the JSON to objects, you can make it return something else by setting the :returning property like so:
+
+    json_request(:returning => :raw) do |r|
+      ...
+    end
+
+The returning property can be set to the following:
+
+* :raw      => the raw JSON response as a string
+* :json     => the JSON parsed to a ruby hash (through JSON.parse)
+* :response => the Voorhees::Response object
+* :objects  => casts the JSON into objects (the default)
+
+#### Voorhees::Request
+
+Both json_service and json_request create Voorhees::Request objects to do their bidding.
+
+If you like you can use this yourself directly.
+
+This sets up a request identical to the json_request messages example above:
+
+    request = Voorhees::Request.new(Message)
+    request.path        = "/messages.json"
+    request.parameters  = {:user_id => self.id} 
+    
+To perform the HTTP request  (returning a Voorhees::Response object):
+
+    response = request.perform
+
+You can now get at the parsed JSON, or convert them to objects:
+
+    response.json       => [{id: 5, subject: "Test", ... }, ...]
+    response.to_objects => [Message, Message, Message, ...]
+
+### Object Hierarchies
+
+Say you have a service which responds with a list of users in the following format:
+
+    curl http://example.com/users.json
+
+    [{
+      "email":"bt@example.com",
+      "username":"btables",
+      "name":"Bobby Tables",
+      "id":1,
+      "address":{
+        "street":"24 Monkey Close",
+        "city":"Somesville",
+        "country":"Somewhere",
+        "coords":{
+          "lat":52.9876,
+          "lon":12.3456
+        }
+      }
+    }]
+
+You can define a service to consume this as follows:
+
+    class User
+      include Voorhees::Resource
+      json_service :list, :path => "http://example.com/users.json"
+    end
+
+Calling User.list will return a list of User instances.
+
+    users = User.list
+    users[0].name => "bt@example.com"
+
+However, what about the address? It just returns as a Hash of parsed JSON:
+
+    users[0].address => {"street":"24 Monkey Close", "city":... }
+    
+If you have an Address class you'd like to use, you can tell it like so:
+
+    json_service :list, :path      => "http://example.com/users.json",
+                        :hierarchy => {:address => Address}
+
+You can nest hierarchies to an infinite depth like so:
+
+    json_service :list, :path      => "http://example.com/users.json",
+                        :hierarchy => {:address => [Address, {:coords => LatLon}]}
+
+Instead of the class name, you can also just use a symbol:
+
+    json_service :list, :path      => "http://example.com/users.json",
+                        :hierarchy => {:address => [:address, {:coords => :lat_lon}]}
+
+With that we can now do:
+
+    users = User.list
+    users[0].name               => "Bobby Tables"
+    users[0].address.country    => "Somewhere"
+    users[0].address.coords.lat => 52.9876
+
+### Requirements
+
+* A JSON library which supports JSON.parse
+* ActiveSupport
+* SystemTimer - falls back on Timer if it's not available
+    
+## Thanks
+
+The ideas and design came from discussions when refactoring [LVS::JSONService](http://github.com/LVS/JSONService) the original of which was 
+developed by [Andy Jeffries](http://github.com/andyjeffries/) for use at LVS
+
+Much discussion with [John Cinnamond](http://github.com/jcinnamond) 
+and [Jason Lee](http://github.com/jlsync)
+
+## Copyright
+
+Copyright (c) 2009 Richard Livsey. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,55 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "voorhees"
+    gem.summary = %Q{Library to consume and interract with JSON services}
+    gem.email = "richard@livsey.org"
+    gem.homepage = "http://github.com/rlivsey/voorhees"
+    gem.authors = ["Richard Livsey"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+begin
+  gem 'ci_reporter'
+  require 'ci/reporter/rake/rspec'
+rescue LoadError
+  # do nothing
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "voorhees #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/examples/twitter.rb

@@ -0,0 +1,85 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'rubygems'
+require 'json'            # use whatever JSON gem you want, as long as it supports JSON.parse
+require 'active_support'  # used for inflector 
+require 'voorhees'
+require 'pp'
+
+Voorhees::Config.setup do |c|
+  c[:base_uri] = "http://twitter.com"
+end
+
+class User
+  include Voorhees::Resource
+  
+  json_service  :get,  
+                :path => "/users/show.json",
+                :hierarchy => {
+                  :status => :tweet
+                }
+  
+  def friends
+    json_request do |r|
+      r.path        = "/statuses/friends.json"
+      r.parameters  = {:id => self.screen_name}
+      r.hierarchy   = {
+        :status => :tweet
+      }
+    end
+  end
+  
+end
+
+class Tweet
+  include Voorhees::Resource
+  
+  json_service  :public_timeline, 
+                :path => "/statuses/public_timeline.json",
+                :hierarchy => {
+                  :user => User # can be a class
+                }
+                
+  json_service  :users_timeline,
+                :path => "/statuses/user_timeline.json",
+                :hierarchy => {
+                  :user => :user # or a symbol
+                }
+  
+end
+
+puts "> tweets = Tweet.public_timeline"
+tweets = Tweet.public_timeline
+
+puts "> tweets[0].class: #{tweets[0].class}"
+puts "> tweets[0].text: #{tweets[0].text}"
+puts "> tweets[0].user.name: #{tweets[0].user.name}"
+
+puts "\n\n"
+puts "> tweets = Tweet.users_timeline(:id => 'rlivsey', :page => 2)"
+tweets = Tweet.users_timeline(:id => 'rlivsey', :page => 2)
+
+puts "> tweets[0].text: #{tweets[0].text}"
+puts "> tweets[0].user.name: #{tweets[0].user.name}"
+
+puts "\n\n"
+
+puts "> rlivsey = User.get(:id => 'rlivsey')"
+rlivsey = User.get(:id => 'rlivsey')
+
+puts "> rlivsey.name: #{rlivsey.name}"
+puts "> rlivsey.location: #{rlivsey.location}"
+puts "> rlivsey.status.text: #{rlivsey.status.text}"
+puts "> rlivsey.status.created_at: #{rlivsey.status.created_at}"
+
+puts "\n\n"
+
+puts "> friends = rlivsey.friends"
+friends = rlivsey.friends
+
+puts "> friends[0].class: #{friends[0].class}"
+puts "> friends[0].name: #{friends[0].name}"
+puts "> friends[0].status.text: #{friends[0].status.text}"
+
+

data/lib/voorhees.rb

@@ -0,0 +1,6 @@
+require "voorhees/logging"
+require "voorhees/config"
+require "voorhees/exceptions"
+require "voorhees/request"
+require "voorhees/response"
+require "voorhees/resource"

data/lib/voorhees/config.rb

@@ -0,0 +1,87 @@
+require 'logger'
+
+module Voorhees
+  module Config    
+    class << self
+      
+      # the configuration hash itself
+      def configuration
+        @configuration ||= defaults
+      end
+      
+      def defaults
+        {
+          :logger              => defined?(RAILS_DEFAULT_LOGGER) ? RAILS_DEFAULT_LOGGER : Logger.new(STDOUT),
+          :timeout             => 10,
+          :retries             => 0,
+          :http_method         => Net::HTTP::Get,
+          :response_class      => Voorhees::Response
+        }
+      end
+      
+      def [](key)
+        configuration[key]
+      end
+      
+      def []=(key, val)
+        configuration[key] = val
+      end
+
+      # remove an item from the configuration
+      def delete(key)
+        configuration.delete(key)
+      end
+      
+      # Return the value of the key, or the default if doesn't exist
+      # 
+      # ==== Examples
+      # 
+      # Voorhees::Config.fetch(:monkey, false)
+      # => false
+      # 
+      def fetch(key, default)
+        configuration.fetch(key, default)
+      end
+
+      def to_hash
+        configuration
+      end      
+
+      # Yields the configuration.
+      # 
+      # ==== Examples
+      #   Voorhees::Config.use do |config|
+      #     config[:debug]    = true
+      #     config.something  = false
+      #   end
+      # 
+      def setup
+        yield self
+        nil
+      end      
+
+      def clear
+        @configuration = {}
+      end
+      
+      def reset
+        @configuration = defaults
+      end
+      
+      # allow getting and setting properties via Voorhees::Config.xxx
+      # 
+      # ==== Examples
+      # Voorhees::Config.debug
+      # Voorhees::Config.debug = false
+      # 
+      def method_missing(method, *args)
+        if method.to_s[-1,1] == '='
+          configuration[method.to_s.tr('=','').to_sym] = *args
+        else
+          configuration[method]
+        end
+      end      
+      
+    end 
+  end
+end