wrest 0.0.5-java

data/README.rdoc

@@ -0,0 +1,101 @@
+= Wrest
+
+(c) Copyright 2009 {Sidu Ponnappa}[http://blog.sidu.in]. All Rights Reserved.
+
+Wrest is a ruby REST client library which allows you to quickly build object oriented wrappers around any web service. It has two components - Wrest Core and Wrest::Resource.
+
+== Installation
+
+The source is available at git://github.com/kaiwren/wrest.git
+
+To install as a Rails plugin, do <tt>script/plugin install git://github.com/kaiwren/wrest.git</tt>
+
+To install the Wrest gem, do <tt>sudo gem install wrest</tt>
+
+== Wrest Core
+
+* Designed to be used as a library, not just a command line REST client
+* Provides basic infrastructure (including an interactive shell) and convenient HTTP wrappers
+* Makes it easy to extend and modify both serialisation, deserialisation and object creation
+* Isn't coupled to Rails (usable in a pure Ruby application to consume any REST api)
+* Can be used both stand alone as well as to build object oriented abstractions around web services (Wrest::Resource is an example of the latter)
+
+=== Usage: Shell
+
+You can launch the interactive Wrest shell by running bin/wrest if you have the source or invoking <tt>wrest</tt> from your prompt if you've installed the gem.
+  $ wrest
+  >> "http://search.yahooapis.com/NewsSearchService/V1/newsSearch?appid=YahooDemo&output=json&query=India&results=3&start=1".to_uri.get
+
+=== Usage: Library
+
+  require 'rubygems'
+  require 'wrest'
+  y "http://search.yahooapis.com/NewsSearchService/V1/newsSearch".to_uri.get(
+									:appid  => 'YahooDemo', 
+									:output => 'xml',
+									:query  => 'India',
+									:results=> '3',
+									:start  => '1'
+								)
+=== Basic Http Calls
+
+==== Get
+
+A couple of ways to get the Yahoo news as hash map (needs the JSON gem - gem install json). 
+
+* This example simply does a get on a uri and figures out the appropriate deserialiser using the content-type (in this case 'text/javascript', which uses Wrest::Translators::Json). See content_types.rb under lib/wrest/mappers/translators.
+ "http://search.yahooapis.com/NewsSearchService/V1/newsSearch?appid=YahooDemo&output=json&query=India&results=3&start=1".to_uri.get.deserialise
+
+* This example does a get on a base uri with several parameters passed to it, resulting in a uri essentially the same as the one above. It also shows how you can use a custom deserialiser to produce a hash-map from the response. 
+ "http://search.yahooapis.com/NewsSearchService/V1/newsSearch".to_uri.get(
+									:appid  => 'YahooDemo', 
+									:output => 'xml',
+									:query  => 'India',
+									:results=> '3',
+									:start  => '1'
+								).deserialise_using(Wrest::Translators::Xml)
+
+
+=== Logging
+
+The Wrest logger can be set and accessed through Wrest.logger and is configured by default to log to STDOUT. If you're using Wrest in a Rails application, you can configure logging by placing the following line in your environment file:
+  Wrest.logger = ActiveRecord::Base.logger
+
+=== Build
+
+Standard options are available and can be listed using <tt>rake -T</tt>. Use rake:rcov for coverage and rake:rdoc to generate documentation.
+
+== Documentation
+
+Wrest RDocs can be found at http://wrest.rubyforge.org/
+
+== Wrest::Resource 
+
+Wrest::Resource is an alternative to ActiveResource which targets Rails REST services; it is currently under development.
+
+* Out of the box support for collections
+* Out of the box support for collection pagination (including support for WillPaginate), both header based and xml attribute based
+* Out of the box support for operations on all the records on the collection
+* Out of the box support for nested resources
+* Out of the box support for cached resources
+* Out of the box support for type-casting data that comes in as parameter strings
+* More natural mapping of deserialised entities to existing classes
+* No communication via exceptions for http error status codes
+* Better extensibility - allows access to request/response objects, avoids class variables, favours symbols over strings etc.
+
+== Dependencies
+
+* gems
+* xmlsimple
+* json
+* rspec
+* rcov
+* active_support
+
+== Support
+
+This project uses Assembla for ticketing: http://www.assembla.com/spaces/wrest/tickets
+
+== Licence
+
+Wrest is released under the Apache 2.0 licence

data/Rakefile

@@ -0,0 +1,243 @@
+# Copyright 2009 Sidu Ponnappa
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+# is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+
+require 'rubygems'
+gem 'rspec'
+require 'rake'
+require 'rake/rdoctask'
+require 'spec'
+require 'spec/rake/spectask'
+
+puts "Building on Ruby #{RUBY_VERSION}, #{RUBY_RELEASE_DATE}, #{RUBY_PLATFORM}"
+
+desc 'Default: run spec tests.'
+task :default => :spec
+
+desc "Run all specs"
+Spec::Rake::SpecTask.new(:spec) do |task|
+  task.spec_files = FileList['spec/wrest/**/*_spec.rb']
+  task.spec_opts = ['--options', 'spec/spec.opts']
+end
+
+desc 'Generate documentation for Wrest'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = 'WRest'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'rcov'
+  require 'rcov/rcovtask'
+  desc "Run all specs in spec directory with RCov"
+  Spec::Rake::SpecTask.new(:rcov) do |t|
+    t.spec_opts = ['--options', "spec/spec.opts"]
+    t.spec_files = FileList["spec/wrest/**/*_spec.rb"]
+    t.rcov = true
+    t.rcov_opts = lambda do
+      IO.readlines("spec/rcov.opts").map {|l| l.chomp.split " "}.flatten
+    end
+    # t.verbose = true
+  end
+rescue LoadError
+  puts "Rcov not available."
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "wrest"
+    gemspec.summary = "REST client library for Ruby."
+    gemspec.description = "Wrest is a REST client library which allows you to quickly build object oriented wrappers around any web service. It has two main components - Wrest Core and Wrest::Resource."
+    gemspec.authors = ["Sidu Ponnappa"]
+    gemspec.email = "ckponnappa@gmail.com"
+    gemspec.homepage = "http://github.com/kaiwren/wrest"
+    gemspec.has_rdoc = true
+    gemspec.rubyforge_project = 'wrest'
+    gemspec.executables = ['wrest']
+    gemspec.require_path = "lib"
+    gemspec.files.exclude 'spec/wrest/meh_spec.rb'
+    gemspec.test_files.exclude 'spec/wrest/meh_spec.rb'
+    gemspec.add_dependency('activesupport', '>= 2.1.0')
+    gemspec.add_dependency('xml-simple', '>= 1.0.11')
+    case RUBY_PLATFORM
+    when /java/
+      gemspec.add_dependency('json-jruby', '>= 1.1.3')  
+      gemspec.platform = 'java'
+    else
+      gemspec.add_dependency('json', '>= 1.1.3')  
+      gemspec.platform = Gem::Platform::RUBY
+    end
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+begin
+  require 'rake/contrib/sshpublisher'
+  namespace :rubyforge do
+
+    desc "Release gem and RDoc documentation to RubyForge"
+    task :release => ["rubyforge:release:gem", "rubyforge:release:docs"]
+
+    namespace :release do
+      desc "Publish RDoc to RubyForge."
+      task :docs => [:rdoc] do
+        config = YAML.load(
+        File.read(File.expand_path('~/.rubyforge/user-config.yml'))
+        )
+
+        host = "#{config['username']}@rubyforge.org"
+        remote_dir = "/var/www/gforge-projects/wrest/"
+        local_dir = 'rdoc'
+
+        Rake::SshDirPublisher.new(host, remote_dir, local_dir).upload
+      end
+    end
+  end
+rescue LoadError
+  puts "Rake SshDirPublisher is unavailable or your rubyforge environment is not configured."
+end
+
+
+namespace (:benchmark) do
+  desc "Create classes to be used in Wrest::Resource vs. ActiveResource"
+  task :setup_test_classes do
+    require 'active_resource'
+    require 'wrest'
+
+    class Ooga < Wrest::Mappers::Resource::Base;end
+      class Booga < ActiveResource::Base; self.site='';end
+      end
+
+      desc "Benchmark when objects are created each time before getting data; i.e there are few queries per instantiation"
+      task :create_and_get => :setup_test_classes do |t|
+
+        n = 10000
+        puts "Running #{n} times per report"
+        Benchmark.bmbm(10) do |rpt|
+          rpt.report("Wrest::Resource") do
+            n.times {
+              ooga = Ooga.new(:id => 5, :profession => 'Natural Magician', :enhanced_by => 'Kai Wren')
+              ooga.profession
+              ooga.profession?
+              ooga.enhanced_by
+              ooga.enhanced_by?
+            }
+          end
+
+          rpt.report("ActiveResource") do
+            n.times {
+              booga = Booga.new(:id => 5, :profession => 'Natural Magician', :enhanced_by => 'Kai Wren')
+              booga.profession
+              booga.profession?
+              booga.enhanced_by
+              booga.enhanced_by?
+            }
+          end
+        end
+      end
+
+      desc "Benchmark when objects are created beforehand; i.e there are many queries per instantiation"
+      task :create_once_and_get => :setup_test_classes do |t|
+
+        n = 10000
+        puts "Running #{n} times per report"
+
+        Benchmark.bmbm(10) do |rpt|
+          rpt.report("Wrest::Resource") do
+            ooga = Ooga.new(:id => 5, :profession => 'Natural Magician', :enhanced_by => 'Kai Wren')
+
+            n.times {
+              ooga.profession
+              ooga.profession?
+              ooga.enhanced_by
+              ooga.enhanced_by?
+            }
+          end
+
+          rpt.report("ActiveResource") do
+            booga = Booga.new(:id => 5, :profession => 'Natural Magician', :enhanced_by => 'Kai Wren')
+
+            n.times {
+              booga.profession
+              booga.profession?
+              booga.enhanced_by
+              booga.enhanced_by?
+            }
+          end
+        end
+      end
+
+      desc "Benchmark objects respond_to? performance without invocation"
+      task :responds_to_before => :setup_test_classes do |t|
+
+        n = 10000
+        puts "Running #{n} times per report"
+
+        Benchmark.bmbm(10) do |rpt|
+          rpt.report("Wrest::Resource") do
+            ooga = Ooga.new(:id => 5, :profession => 'Natural Magician', :enhanced_by => 'Kai Wren')
+
+            n.times {
+              ooga.respond_to?(:profession)
+              ooga.respond_to?(:profession?)
+              ooga.respond_to?(:profession=)
+            }
+          end
+
+          rpt.report("ActiveResource") do
+            booga = Booga.new(:id => 5, :profession => 'Natural Magician', :enhanced_by => 'Kai Wren')
+
+            n.times {
+              booga.respond_to?(:profession)
+              booga.respond_to?(:profession?)
+              booga.respond_to?(:profession=)
+            }
+          end
+        end
+      end
+
+      desc "Benchmark objects respond_to? performance after invocation"
+      task :responds_to_after => :setup_test_classes do |t|
+
+        n = 10000
+        puts "Running #{n} times per report"
+
+        Benchmark.bmbm(10) do |rpt|
+          rpt.report("Wrest::Resource") do
+            ooga = Ooga.new(:id => 5, :profession => 'Natural Magician', :enhanced_by => 'Kai Wren')
+            ooga.profession
+            ooga.profession?
+            ooga.profession = ''
+
+            n.times {
+              ooga.respond_to?(:profession)
+              ooga.respond_to?(:profession?)
+              ooga.respond_to?(:profession=)
+            }
+          end
+
+          rpt.report("ActiveResource") do
+            booga = Booga.new(:id => 5, :profession => 'Natural Magician', :enhanced_by => 'Kai Wren')
+            booga.profession
+            booga.profession?
+            booga.profession = ''
+
+            n.times {
+              booga.respond_to?(:profession)
+              booga.respond_to?(:profession?)
+              booga.respond_to?(:profession=)
+            }
+          end
+        end
+      end
+    end

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:patch: 5
+:minor: 0
+:major: 0

data/bin/jwrest

@@ -0,0 +1,3 @@
+#!/usr/bin/env jruby
+
+load(File.dirname(__FILE__)+'/wrest_shell.rb')

data/bin/wrest

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+
+load(File.dirname(__FILE__)+'/wrest_shell.rb')

data/bin/wrest_shell.rb

@@ -0,0 +1,21 @@
+puts "Ruby #{RUBY_VERSION}, #{RUBY_RELEASE_DATE}, #{RUBY_PLATFORM}"
+
+entry_point = "#{File.dirname(__FILE__)}/../lib/wrest.rb"
+version = "#{File.dirname(__FILE__)}/../lib/wrest/version"
+
+irb = RUBY_PLATFORM =~ /(:?mswin|mingw)/ ? 'irb.bat' : 'irb'
+
+require 'optparse'
+options = { :irb => irb }
+OptionParser.new do |opt|
+  opt.banner = "Usage: console [options]"
+  opt.on("--irb=[#{irb}]", 'Invoke a different irb.') { |v| options[:irb] = v }
+  opt.parse!(ARGV)
+end
+
+libs =  " -r irb/completion"
+libs << " -r #{entry_point}"
+
+require version
+puts "Loading Wrest #{Wrest::VERSION::STRING}"
+exec "#{options[:irb]} #{libs} --simple-prompt"

data/lib/wrest.rb

@@ -0,0 +1,41 @@
+# Copyright 2009 Sidu Ponnappa
+# Licensed under the Apache License, Version 2.0 (the "License"); 
+# you may not use this file except in compliance with the License. 
+# You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 
+# Unless required by applicable law or agreed to in writing, software distributed under the License 
+# is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
+# See the License for the specific language governing permissions and limitations under the License. 
+
+require 'rubygems'
+require 'net/http'
+require 'net/https'
+require 'forwardable'
+require 'date'
+require 'cgi'
+require 'base64'
+require 'logger'
+require 'benchmark'
+require 'active_support'
+
+WREST_ROOT = File.dirname(__FILE__)
+
+module Wrest
+  def self.logger=(logger)
+    @logger = logger
+  end
+  
+  def self.logger
+    @logger
+  end
+end
+
+Wrest.logger = Logger.new(STDOUT)
+Wrest.logger.level = Logger::DEBUG
+
+source_dirs = ["/wrest/core_ext/*.rb", "/wrest/*.rb"]
+
+source_dirs.each{|directory|
+  Dir["#{File.expand_path(File.dirname(__FILE__) + directory)}"].each { |file|
+    require file
+  }
+}

data/lib/wrest/components.rb

@@ -0,0 +1,19 @@
+# Copyright 2009 Sidu Ponnappa
+
+# Licensed under the Apache License, Version 2.0 (the "License"); 
+# you may not use this file except in compliance with the License. 
+# You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 
+# Unless required by applicable law or agreed to in writing, software distributed under the License 
+# is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
+# See the License for the specific language governing permissions and limitations under the License. 
+
+module Wrest #:nodoc:
+  # A component is a building block that can
+  # be used while building an object oriented wrapper
+  # around a REST service
+  module Components
+  end
+end
+
+require "#{WREST_ROOT}/wrest/components/attributes_container"
+require "#{WREST_ROOT}/wrest/components/mutators"