wrest 0.0.8-java → 0.0.9-java

data/README.rdoc

@@ -1,15 +1,15 @@
-= Wrest 
+= Wrest 0.0.9
 
 (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. 
+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. If you want to be notified whenever new features are added to Wrest, you can subscribe to my {twitter feed}[http://twitter.com/ponnappa].
 
-If you were wondering why the words 'demon', 'chi' and 'puppies' (among others) show up in nearly every example and spec, it's because they all refer to characters and ideas from {Roger Zelazny's}[http://en.wikipedia.org/wiki/Roger_Zelazny] last book, 'Lord Demon.'
+If you were wondering why the words 'demon', 'chi' and 'fu-puppies' (among others) show up in nearly every example and spec, it's because they all refer to characters and ideas from {Roger Zelazny's}[http://en.wikipedia.org/wiki/Roger_Zelazny] last book, 'Lord Demon.'
 
 == Wrest Core: Features
 
-* Provides convenient HTTP wrappers, serialisation and deserialisation with caching and redirect handling in the works.
-* Designed to be used as a library, not just a command line REST client (fewer class methods, more object oriented)
+* Provides convenient HTTP wrappers, redirect handling, serialisation and deserialisation with response caching in the works.
+* Designed to be used as a library, not just a command line REST client (fewer class/static methods, more object oriented)
 * Isn't coupled to Rails (usable in a pure Ruby application to consume any HTTP/REST api)
 * Can be used both stand alone as well as to build object oriented abstractions around resources and web services (Wrest::Resource is an example of the latter)
 
@@ -23,8 +23,9 @@ 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 is also available as a gem for JRuby; you can instally it by running <tt>(sudo) jruby -S gem install wrest</tt>.
+To install the Wrest gem, do <tt>(sudo) gem install wrest</tt>. Wrest supports both Ruby 1.8 and 1.9.
+
+Wrest is also available as a gem for JRuby; you can install it by running <tt>(sudo) jruby -S gem install wrest</tt>.
 
 === Usage: Shell
 
@@ -89,24 +90,26 @@ To find out what actions are permitted on a URI:
 
 === Usage: Attributes Container
 
-Allows any class to hold an attributes hash, somewhat like ActiveResource. It also supports several extensions to this base fuctionality such as support for typecasting attribute values.
+Allows any class to hold an attributes hash, somewhat like ActiveResource. It also supports several extensions to this base fuctionality such as support for typecasting attribute values. See examples/twitter.rb and examples/wow_realm_status.rb for more samples.
 
 Example:
 
  class Demon
    include Wrest::Components::AttributesContainer
-   include Wrest::Components::AttributesContainer::Typecaster
 
-   always_has	      :id  
+   always_has       :id
    typecast         :age          =>  as_integer,
                     :chi          =>  lambda{|chi| Chi.new(chi)}
+
+   alias_accessors  :chi => :energy                  
  end
 
- kai_wren = Demon.new('id => '1', 'age' => '1500', 'chi' => '1024', 'teacher' => 'Viss')
- kai_wren.id			# => '1'
- kai_wren.age			# => 1500
- kai_wren.chi			# => #<Chi:0x113af8c @count="1024">
- kai_wren.teacher		# => 'Viss'
+ kai_wren = Demon.new('id' => '1', 'age' => '1500', 'chi' => '1024', 'teacher' => 'Viss')
+ kai_wren.id       # => '1'
+ kai_wren.age      # => 1500
+ kai_wren.chi      # => #<Chi:0x113af8c @count="1024">
+ kai_wren.energy   # => #<Chi:0x113af8c @count="1024">
+ kai_wren.teacher  # => 'Viss'
 
 === Usage: Logging
 
@@ -125,6 +128,8 @@ Wrest RDocs can be found at http://wrest.rubyforge.org
 
 Wrest::Resource is an alternative to Rails' ActiveResource. It targets Rails REST (well, POX, since Rails isn't really RESTful) services and is currently under development. Since no single REST library can provide an object oriented wrapper suitable for _all_ available web services, it follows that Wrest should focus on providing you with the tools to help you roll your own. Wrest::Resource is an example of this - an object oriented wrapper for the kind of REST APIs exposed by Rails applications, that you would otherwise use ActiveResource to consume.
 
+If you're looking for help doing this on Rails on the server side, take a look at {resource_full}[http://github.com/bguthrie/resource_full], a Rails plugin that makes RESTful Rails a whole order of magnitude easier. resource_full is a stable project and is currently in use in production.
+
 
 * No more pretending that REST resources are the same as records in a database (yeah, no more freaking ActiveResource::Connection)
 * Treat put as 'create or update,' not just 'update'
@@ -147,19 +152,21 @@ Wrest::Resource is an alternative to Rails' ActiveResource. It targets Rails RES
 == Dependencies
 
 === Source
+
 * gems
 * json (json-jruby on JRuby)
 * active_support
 * ruby-libxml (Recommended, will fall back to REXML if absent; be aware that Wrest uses ActiveSupport::XmlMini, so if you're using Wrest as a plugin in a Rails application, all xml parsing across the application will switch to using libxml if it's available. You're free to change this by hand by using the ActiveSupport::XmlMini.backend= method.)
 
 === Build
+
 * rspec
 * rcov (unsupported on JRuby)
 * jeweler
 
-== Support
+== Roadmap
 
-This project uses Assembla for ticketing: http://www.assembla.com/spaces/wrest/tickets
+Features that are planned, in progress or already implemented are documented in the {CHANGELOG}[http://github.com/kaiwren/wrest/tree/master/CHANGELOG] starting from version 0.0.8.
 
 == Licence
 

data/Rakefile

@@ -31,7 +31,7 @@ task :default => :spec
 
 desc "Run all specs"
 Spec::Rake::SpecTask.new(:spec) do |task|
-  task.spec_files = FileList['spec/wrest/**/*_spec.rb']
+  task.spec_files = FileList['spec/unit/wrest/**/*_spec.rb']
   task.spec_opts = ['--options', 'spec/spec.opts']
 end
 
@@ -56,7 +56,7 @@ begin
   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.spec_files = FileList["spec/unit/wrest/**/*_spec.rb"]
     t.rcov = true
     t.rcov_opts = lambda do
       IO.readlines("spec/rcov.opts").map {|l| l.chomp.split " "}.flatten
@@ -80,8 +80,8 @@ begin
     gemspec.rubyforge_project = 'wrest'
     gemspec.executables = ['wrest', 'jwrest']
     gemspec.require_path = "lib"
-    gemspec.files.exclude 'spec/wrest/meh_spec.rb'
-    gemspec.test_files.exclude 'spec/wrest/meh_spec.rb'
+    gemspec.files.exclude 'spec/unit/wrest/meh_spec.rb'
+    gemspec.test_files.exclude 'spec/unit/wrest/meh_spec.rb'
     gemspec.add_dependency('activesupport', '>= 2.3.2')
     case RUBY_PLATFORM
     when /java/
@@ -94,7 +94,7 @@ begin
   end
 rescue LoadError
   puts "Jeweler not available. Install it with: gem install technicalpickles-jeweler -s http://gems.github.com"
-  puts "If you're using JRuby, install it with: jruby -S gem install technicalpickles-jeweler -s http://gems.github.com --version '=0.11.0'"
+  puts "If you're using JRuby and are having trouble installing jeweler, try installing the git (gem install git) and rubyforge (gem install rubyforge) gems by hand. Also remember to update gems itself (jruby -S gem update --system)."
 end
 
 begin
@@ -120,7 +120,7 @@ begin
     end
   end
 rescue LoadError
-  puts "Rake SshDirPublisher is unavailable or your rubyforge environment is not configured."
+  puts "Rake SshDirPublisher is unavailable or your rubyforge environment is not configured. You may need to run `gem install rubyforge`"
 end
 
 

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
-:patch: 8
+:patch: 9
 :minor: 0
 :major: 0

data/examples/delicious.rb

@@ -13,6 +13,10 @@ require 'pp'
 Wrest.logger = Logger.new(STDOUT)
 Wrest.logger.level = Logger::DEBUG  # Set this to Logger::INFO or higher to disable request logging
 
+# This example demonstrates the usage of GET, POST, PUT and
+# DELETE over HTTPS. Its also shows how Wrest::Uris can have
+# paths extended making accessing an API easy as pie.
+#
 # API reference: http://delicious.com/help/api
 class Delicious
   def initialize(options)
@@ -45,14 +49,14 @@ pp account.bookmark(
     :tags => 'ruby hacking'
   ).deserialise
   
-puts '----------'
+puts '', '*'*70, ''
 
 pp account.bookmarks(:tag => 'rails', :dt => '20090712').deserialise
 
-puts '----------'
+puts '', '*'*70, ''
 
 pp recently_saved_uris = account.recent(:tag => 'ruby').deserialise["posts"]["post"].collect{|bookmark| bookmark['href']}
 
-puts '----------'
+puts '', '*'*70, ''
 
 pp account.delete(:url => 'http://blog.sidu.in/search/label/ruby').deserialise

data/examples/redirection.rb

@@ -0,0 +1,27 @@
+# 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 File.expand_path(File.dirname(__FILE__) + "/../lib/wrest")
+require 'pp'
+
+Wrest.logger = Logger.new(STDOUT)
+Wrest.logger.level = Logger::DEBUG  # Set this to Logger::INFO or higher to disable request logging
+
+# google.com redirects to www.google.com so this is live test for redirection
+pp 'http://google.com'.to_uri.get.body
+
+puts '', '*'*70, ''
+
+# Do a get with auto follow redirects turned off
+pp 'http://google.com'.to_uri(:follow_redirects => false).get.body
+
+puts '', '*'*70, ''
+
+# Do a get with auto follow redirects limited, causing an exception.
+'http://google.com'.to_uri(:follow_redirects_limit => 1).get.body

data/examples/twitter.rb

@@ -0,0 +1,78 @@
+# 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 File.expand_path(File.dirname(__FILE__) + "/../lib/wrest")
+require 'pp'
+
+Wrest.logger = Logger.new(STDOUT)
+Wrest.logger.level = Logger::DEBUG  # Set this to Logger::INFO or higher to disable request logging
+
+# This example shows a more object oriented approach
+# to accessing Twitter using Wrest.
+# 
+# Twitter is your twitter account. Every tweet is wrapped in
+# an instance of Tweet. Every Tweet has one TwitterUser.
+
+class Twitter  
+  def initialize(options)
+    @uri = "https://twitter.com".to_uri(options)
+  end
+  
+  # which can be :friends, :user or :public
+  # options[:query] can be things like since, since_id, count, etc.
+  def timeline(which = :friends, options={})
+    @uri["/statuses/#{which}_timeline.json"].get(options).deserialise.collect{|tweet| Tweet.new(tweet)}
+  end
+  
+  def post(text)
+    Tweet.new @uri['/statuses/update.json'].post('', {'User-Agent' => "Wrest/#{Wrest::VERSION::STRING}"}, {:status => text}).deserialise
+  end  
+end
+
+class TwitterUser
+  # This will turn this class into a wrapper
+  # for the deserialised data from a response.
+  #
+  # All the keys in the hash are exposed as methods.
+  include Wrest::Components::AttributesContainer
+
+  # We'd prefer the user's profile url to be
+  # a Wrest::Uri rather than a String, wouldn't we?
+  #
+  # Remember, using typecasting _will_
+  # slow down instance construction marginally, so turn it on
+  # only if you need it.
+  typecast :url => lambda{|url| url.to_uri}
+end
+
+class Tweet
+  include Wrest::Components::AttributesContainer
+
+  typecast  :user => lambda{|user| TwitterUser.new(user) }
+end
+
+
+twitter = Twitter.new(:username => 'ponnappa', :password => 'ha!likeImchecking*that*in')
+
+pp twitter.post("This tweet via the Twitter example in #wrest #{Wrest::VERSION::STRING}, http://github.com/kaiwren/wrest")
+
+puts '', '*'*70, ''
+
+tweets = twitter.timeline(:friends, :since_id => 20751449)
+
+# Print the name of the first user in my timeline.
+puts tweets.first.user.name
+
+puts '', '*'*70, ''
+
+# Just remember that not everyone on Twitter has a
+# url. On the other hand, some have more than one.
+# This is just a cute little example that deals with
+# the simple case of a single url.
+puts tweets.first.user.url.get.body

data/{spec/wrest/http/request_spec.rb → examples/twitter_public_timeline.rb}

@@ -7,16 +7,19 @@
 # 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 File.dirname(__FILE__) + '/../../spec_helper'
+require File.expand_path(File.dirname(__FILE__) + "/../lib/wrest")
+require 'pp'
 
-describe Wrest::Http::Request do
-  it "should convert all symbols in header keys to strings" do
-    Wrest::Http::Request.new(
-                'http://localhost/foo'.to_uri, Net::HTTP::Get, {}, 
-                nil, 'Content-Type' => 'application/xml', :per_page => '10'
-                ).headers.should == {
-                  'Content-Type' => 'application/xml',
-                  'per_page' => '10'
-                }
-  end
-end
+Wrest.logger = Logger.new(STDOUT)
+Wrest.logger.level = Logger::DEBUG  # Set this to Logger::INFO or higher to disable request logging
+
+
+# This is a basic example demonstrating GET and json deserialisation.
+
+response = 'http://twitter.com/statuses/public_timeline.json'.to_uri.get
+
+puts "Code: #{response.code}"
+puts "Message: #{response.message}"
+puts "Headers: #{response.headers.inspect}"
+puts "Body: #{response.body.inspect}"
+puts "Deserialised: #{response.deserialise.inspect}"

data/examples/wow_realm_status.rb

@@ -16,7 +16,6 @@ include Wrest
 
 class Realm
   include Components::AttributesContainer
-  include Components::AttributesContainer::Typecaster
 
   typecast  :t => lambda{|type| 
                     case type
@@ -40,6 +39,11 @@ class Realm
                       when '4' then 'Max'
                     end  
                   }
+                  
+  alias_accessors :t => :type, 
+                  :s => :status,
+                  :l => :load,
+                  :n => :name
   
   def available?
     self.s == 'Available'
@@ -48,10 +52,10 @@ end
 
 realms = "http://www.worldofwarcraft.com/realmstatus/status.xml".to_uri.get.deserialise['page']['rs']['r'].collect{|data| Realm.new(data)}
 
-puts "Status of Nagrand: #{realms.find{|realm| realm.n == 'Nagrand'}.s}"
+puts "Status of Nagrand: #{realms.find{|realm| realm.name == 'Nagrand'}.status}"
 puts
 puts "All Available Realms:"
 puts
 puts "Realm\tLoad\tType"
 puts "-----------"
-realms.select(&:available?).each{|realm| puts "#{realm.n}\t#{realm.l}\t#{realm.t}" }
+realms.select(&:available?).each{|realm| puts "#{realm.name}\t#{realm.load}\t#{realm.type}" }

data/lib/wrest/components/attributes_container.rb

@@ -13,6 +13,7 @@ module Wrest
 end
 
 require "#{WREST_ROOT}/wrest/components/attributes_container/typecaster"
+require "#{WREST_ROOT}/wrest/components/attributes_container/alias_accessors"
 
 module Wrest::Components
 
@@ -57,7 +58,11 @@ module Wrest::Components
   module AttributesContainer
     def self.included(klass) #:nodoc:
       klass.extend AttributesContainer::ClassMethods
-      klass.class_eval{ include AttributesContainer::InstanceMethods }
+      klass.extend AttributesContainer::Typecaster::Helpers
+      klass.class_eval do 
+        include AttributesContainer::InstanceMethods
+        include AttributesContainer::AliasAccessors
+      end  
     end
 
     def self.build_attribute_getter(attribute_name) #:nodoc:
@@ -74,9 +79,9 @@ module Wrest::Components
 
     module ClassMethods
       # This macro explicitly creates getter, setter and query methods on
-      # a class, overriding any exisiting methods with the same names.
-      # This can be used when attribute names clash with method names;
-      # an example would be Rails REST services which frequently make use
+      # an AttributesContainer, overriding any exisiting methods with the same names.
+      # This can be used when attribute names clash with existing method names;
+      # an example would be Rails REST resources which frequently make use
       # an attribute named <tt>id</tt> which clashes with Object#id. Also,
       # this can be used as a performance optimisation if the incoming
       # attributes are known beforehand.
@@ -89,6 +94,19 @@ module Wrest::Components
           )
         end
       end
+      
+      # This is a convenience macro which includes 
+      # Wrest::Components::AttributesContainer::Typecaster into
+      # the class (effectively overwriting this method) before delegating to 
+      # the actual typecast method that is a part of that module.
+      # This saves us the effort of explicitly doing the include. Easy to use API is king.
+      #
+      # Remember that using typecast carries a performance penalty.
+      # See Wrest::Components::AttributesContainer::Typecaster for the actual docs.
+      def typecast(cast_map)
+        self.class_eval{ include Wrest::Components::AttributesContainer::Typecaster }
+        self.typecast cast_map
+      end
     end
 
     module InstanceMethods
@@ -119,7 +137,7 @@ module Wrest::Components
       def method_missing(method_sym, *arguments)
         method_name = method_sym.to_s
         attribute_name = method_name.gsub(/(\?$)|(=$)/, '')
-        if @attributes.include?(attribute_name.to_sym) || method_name.last == '='
+        if @attributes.include?(attribute_name.to_sym) || method_name.last == '=' || method_name.last == '?'
           case method_name.last
           when '='
             self.instance_eval AttributesContainer.build_attribute_setter(attribute_name)

data/lib/wrest/components/attributes_container/alias_accessors.rb

@@ -0,0 +1,66 @@
+# 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
+  module Components::AttributesContainer
+    module AliasAccessors
+      def self.included(klass) #:nodoc:
+        klass.extend AliasAccessors::ClassMethods
+      end
+
+      def self.build_aliased_attribute_getter(attribute_name, alias_name) #:nodoc:
+        "def #{alias_name};#{attribute_name};end;"
+      end
+
+      def self.build_aliased_attribute_setter(attribute_name, alias_name) #:nodoc:
+        "def #{alias_name}=(value);self.#{attribute_name}=value;end;"
+      end
+
+      def self.build_aliased_attribute_queryer(attribute_name, alias_name) #:nodoc:
+        "def #{alias_name}?;self.#{attribute_name}?;end;"
+      end
+      
+      module ClassMethods
+        # Creates an alias set of getter, setter and query methods for 
+        # attributes that aren't quite the way you'd like them to be; this
+        # is especially useful when you have no control over the source web
+        # sevice/resource.
+        #
+        # For example, lets say that a particular resource exposes a
+        # User's age as 'a' and sex as s. Typically, you'd have to access it as
+        # user.a and user.s whereas you's like to access it as user.age and user.sex.
+        # This is where alias_accessors comes into the picture. Your User class would
+        # look somethig like this:
+        #
+        #  class User
+        #    include Wrest::Components::AttributesContainer
+        #
+        #    alias_accessors  :a => :age,
+        #                     :s => :sex
+        #  end
+        # This would create the methods user.age, user.age= and user.age? which delegate
+        # to user.a, user.a= and user.a? respectively. Ditto for s to sex.
+        #
+        # See examples/wow_realm_status.rb for a working example.
+        # 
+        # WARNING: If you try to create an alias with the same name as the attribute,
+        # and then use it, you _will_ cause an infinite loop.
+        def alias_accessors(alias_map)
+          alias_map.each do |attribute_name, alias_name|
+            self.class_eval(
+            AliasAccessors.build_aliased_attribute_getter(attribute_name, alias_name) +
+            AliasAccessors.build_aliased_attribute_setter(attribute_name, alias_name) +
+            AliasAccessors.build_aliased_attribute_queryer(attribute_name, alias_name)
+            )
+          end
+        end
+      end
+    end
+  end
+end