wrest 0.0.5-java → 0.0.6-java

data/README.rdoc

@@ -2,7 +2,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. 
+
+Since no single framework 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 with ease. Wrest::Resource is an example of this - an object oriented wrapper for the kind of REST APIs exposed by Rails applications built using Wrest Core.
 
 == Installation
 
@@ -10,13 +12,12 @@ 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>
+To install the Wrest gem, do <tt>sudo gem install wrest</tt>; Wrest is also available as a gem for JRuby using the same command.
 
 == 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
+* Provides infrastructure components such as convenient HTTP wrappers api, caching, redirect handling, serialisation, deserialisation etc.
 * 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)
 
@@ -46,14 +47,22 @@ A couple of ways to get the Yahoo news as hash map (needs the JSON gem - gem ins
 * 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)
+* 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 specify a custom deserialiser to produce a hash-map from the response, as well as a hash mutator to clean up the deserialised hash.
+  require 'rubygems'
+  require 'wrest'
+
+  include Wrest::Components
+  p "http://search.yahooapis.com/NewsSearchService/V1/newsSearch".to_uri.get(
+																			  :appid  => 'YahooDemo', 
+																			  :output => 'xml',
+																			  :query  => 'India',
+																			  :results=> '3',
+																			  :start  => '1'
+																			).deserialise_using(
+																			  Translators::Xml
+																			).mutate_using(
+																			  Mutators::XmlSimpleTypeCaster.new
+																			)
 
 
 === Logging
@@ -67,12 +76,13 @@ Standard options are available and can be listed using <tt>rake -T</tt>. Use rak
 
 == Documentation
 
-Wrest RDocs can be found at http://wrest.rubyforge.org/
+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.
+Wrest::Resource is an alternative to ActiveResource. It targets Rails REST services and is currently under development.
 
+* No more pretending that REST resources are the same as database records
 * 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
@@ -85,13 +95,17 @@ Wrest::Resource is an alternative to ActiveResource which targets Rails REST ser
 
 == Dependencies
 
+=== Source
 * gems
 * xmlsimple
-* json
-* rspec
-* rcov
+* json (json-jruby on JRuby)
 * active_support
 
+=== Build
+* rspec
+* rcov (unsupported on JRuby)
+* jeweler
+
 == Support
 
 This project uses Assembla for ticketing: http://www.assembla.com/spaces/wrest/tickets

data/Rakefile

@@ -10,7 +10,6 @@
 require 'rubygems'
 gem 'rspec'
 require 'rake'
-require 'rake/rdoctask'
 require 'spec'
 require 'spec/rake/spectask'
 
@@ -25,10 +24,16 @@ Spec::Rake::SpecTask.new(:spec) do |task|
   task.spec_opts = ['--options', 'spec/spec.opts']
 end
 
+begin
+  require 'hanna/rdoctask'
+rescue LoadError
+  puts 'Hanna not available, using standard Rake rdoctask. Fix this by running gem install mislav-hanna.'
+  require 'rake/rdoctask'
+end  
 desc 'Generate documentation for Wrest'
 Rake::RDocTask.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = 'WRest'
+  rdoc.title = 'Wrest Documentation'
   rdoc.options << '--line-numbers' << '--inline-source'
   rdoc.rdoc_files.include('README.rdoc')
   rdoc.rdoc_files.include('lib/**/*.rb')

data/VERSION.yml

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

data/lib/wrest/components.rb

@@ -15,5 +15,7 @@ module Wrest #:nodoc:
   end
 end
 
+require "#{WREST_ROOT}/wrest/components/typecast_helpers"
 require "#{WREST_ROOT}/wrest/components/attributes_container"
-require "#{WREST_ROOT}/wrest/components/mutators"
+require "#{WREST_ROOT}/wrest/components/mutators"
+require "#{WREST_ROOT}/wrest/components/translators"

data/lib/wrest/components/attributes_container.rb

@@ -17,26 +17,39 @@ module Wrest::Components #:nodoc:
   # <tt>respond_to?</tt> however will respond as though 
   # they are all already present.
   # This means that two different instances of the same 
-  # <tt>AttributesContainer</tt> could well have
+  # AttributesContainer could well have
   # different attribute getters/setters/query methods.
-  # 
-  # Note that this means the first call to a particular
+  #
+  # Note that the first call to a particular getter/setter/query
   # method will be slower because the method is defined
   # at that point; subsequent calls will be much faster.
   #
-  # If you're implementing your own initialize method
-  # remember to delegate to the default initialize 
-  # of AttributesContainer by invoking <tt>super(attributes)</tt>
   # Also keep in mind that attribute getter/setter/query methods
   # will _not_ override any existing methods on the class.
   #
   # In situations where this is a problem, such as a client consuming Rails
   # REST services where <tt>id</tt> is a common attribute and clashes with
-  # Object#id it is recommended to create getter/setter/query methods
-  # on the class (which affects all instances) using the <tt>has_attributes</tt> macro.
+  # Object#id, it is recommended to create getter/setter/query methods
+  # on the class (which affects all instances) using the +has_attributes+ macro. 
+  #
+  # If you're implementing your own initialize method
+  # remember to delegate to the default initialize 
+  # of AttributesContainer by invoking <tt>super(attributes)</tt>
+  #
+  # Example:
+  #  class ShenCoin
+  #    include Wrest::Components::AttributesContainer
+  #
+  #    has_attributes  :id
+  #    typecast        :id => as_integer
+  #  end 
+  #  coin = ShenCoin.new(:id => '5', :chi_count => 500, :owner => 'Kai Wren')
+  #  coin.id    # => 5
+  #  coin.owner # => 'Kai Wren'
   module AttributesContainer
     def self.included(klass) #:nodoc:
       klass.extend AttributesContainer::ClassMethods
+      klass.extend TypecastHelpers
       klass.class_eval{ include AttributesContainer::InstanceMethods }
     end
     
@@ -59,8 +72,7 @@ module Wrest::Components #:nodoc:
       # an example would be Rails REST services 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, as defining methods on the first 
-      # invocation is no longer necessary.      
+      # attributes are known beforehand.
       def has_attributes(*attribute_names)
         attribute_names.each do |attribute_name|
           self.class_eval(
@@ -70,6 +82,45 @@ module Wrest::Components #:nodoc:
           ) 
         end
       end
+      
+      # Accepts a set of attribute-name/lambda pairs which are used
+      # to typecast string values injected through the constructor.
+      # Typically needed when populating an +AttributesContainer+
+      # directly from request params. Typecasting kicks in for
+      # a given value _only_ if it is a string.
+      #
+      # Typcast information is inherited by subclasses; however be
+      # aware that explicitly invoking +typecast+ in a subclass will
+      # discard inherited typecast information leaving only the casts
+      # defined in the subclass.
+      #
+      # Common typecasts such as integer, float, datetime etc. are
+      # available through predefined helpers. See TypecastHelpers
+      # for a full list.
+      #
+      # Example:
+      #
+      #  class Demon
+      #    include Wrest::Components::AttributesContainer
+      #    typecast :age  =>  as_integer,
+      #             :chi  =>  lambda{|chi| Chi.new(chi)}  
+      #  end
+      #  kai_wren = Demon.new('age' => '1500', 'chi' => '1024')
+      #  kai_wren.age # => 1500   
+      #  kai_wren.chi # => #<Chi:0x113af8c @count="1024">   
+      def typecast(cast_map)
+        @typecast_map = @typecast_map ? @typecast_map.merge(cast_map.symbolize_keys) : cast_map.symbolize_keys
+      end
+      
+      def typecast_map #:nodoc:
+        if defined?(@typecast_map)
+          @typecast_map
+        elsif superclass != Object && superclass.respond_to?(:typecast_map)
+          superclass.typecast_map
+        else
+          {}  
+        end
+      end  
     end
        
     module InstanceMethods
@@ -81,6 +132,10 @@ module Wrest::Components #:nodoc:
       # own class.
       def initialize(attributes = {})
         @attributes = attributes.symbolize_keys
+        self.class.typecast_map.each do |key, typecaster|
+          value = @attributes[key]
+          @attributes[key] = typecaster.call(value) if value.is_a?(String)
+        end
         @interface = Module.new
         self.extend @interface
       end

data/lib/wrest/components/mutators.rb

@@ -18,4 +18,5 @@ module Wrest #:nodoc:
 end
 
 require "#{WREST_ROOT}/wrest/components/mutators/base"
-require "#{WREST_ROOT}/wrest/components/mutators/xml_simple_type_caster"
+require "#{WREST_ROOT}/wrest/components/mutators/xml_simple_type_caster"
+require "#{WREST_ROOT}/wrest/components/mutators/camel_to_snake_case"

data/lib/wrest/components/mutators/base.rb

@@ -7,21 +7,37 @@
 # 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. 
 
-# This is a Null Object implementation of a
-# hash mutator that will leave the contents
-# of any hash it is applied to unchanged.
+# This is a base implementation of a
+# hash mutator that ensures that the <tt>mutate</tt> method
+# will chain to the next mutator by using a
+# template method.
 class Wrest::Components::Mutators::Base
-  # This method operates on a tuple (well, pair)
-  # from a hash map.
-  # Iterating over any hash using each injects
+  attr_reader :next_mutator
+    
+  def initialize(next_mutator = nil)
+    @next_mutator = next_mutator
+  end
+  
+  # This is a template method which operates on a tuple (well, pair)
+  # from a hash map and guarantees mutator chaining.
+  #
+  # Iterating over any hash using <tt>each</tt> injects
   # each key/value pair from the hash in the
   # form of an array.
-  # Thus the tuple this method expects 
-  # is simply [:key, :value]
+  # This method expects of this form as an argument, i.e.
+  # an array with the structure [:key, :value]
   #
-  # Since this is a Null Object, this method
-  # simply returns the tuple unchanged
+  # The implementation of the mutation is achieved by
+  # overriding the <tt>do_mutate</tt> method in a subclass.
+  # Note that failing to do so will result in an exception
+  # at runtime.
   def mutate(tuple)
-    tuple
+    out_tuple = do_mutate(tuple)
+    next_mutator ? next_mutator.mutate(out_tuple) : out_tuple
+  end
+  
+  protected
+  def do_mutate(tuple)
+    raise Wrest::Exceptions::MethodNotOverriddenException
   end
 end

data/lib/wrest/components/mutators/camel_to_snake_case.rb

@@ -0,0 +1,20 @@
+# 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::Components
+  class Mutators::CamelToSnakeCase < Mutators::Base
+    # Converts the key to snake case
+    #
+    # Example:
+    #  Mutators::CamelToSnakeCase.new.mutate(['Spirit-Sword', 'true'])  # => ['spirit_sword', 'true']
+    def do_mutate(tuple)
+      [tuple.first.underscore, tuple.last]
+    end
+  end
+end

data/lib/wrest/components/mutators/xml_simple_type_caster.rb

@@ -1,31 +1,35 @@
 # 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. 
+# 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.
 
 # This mutator undertands how do type casting
 # using the type data embedded in a hash
 # created by deserialising an xml using
 # xml-simple
-class Wrest::Components::Mutators::XmlSimpleTypeCaster
-  def mutate(tuple)
-    out_key = tuple.first.underscore
-    in_value = tuple.last[0]
-    out_value = in_value
-    
-    case in_value
-    when Hash
-      if in_value["nil"] == "true"
-        out_value = nil
-      elsif in_value["type"] == "integer"
-        out_value = in_value["content"].to_i
+module Wrest::Components
+  class Mutators::XmlSimpleTypeCaster < Mutators::Base
+    def do_mutate(tuple)
+      out_key = tuple.first
+      in_value = tuple.last[0]
+      out_value = in_value
+
+      case in_value
+      when Hash
+        if in_value['nil'] == 'true'
+          out_value = nil
+        elsif in_value.key?('type')
+          out_value = ActiveSupport::CoreExtensions::Hash::Conversions::XML_PARSING[in_value['type']].call(in_value['content'])
+        else
+          out_value = in_value.mutate_using(self)
+        end
       end
+
+      [out_key, out_value]
     end
-      
-    [out_key, out_value]
   end
-end
+end

data/lib/wrest/{translators.rb → components/translators.rb}

@@ -7,19 +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. 
  
-module Wrest
+module Wrest::Components #:nodoc:
   # Contains strategies/lambdas which know how to deserialise
   # different content types.
   module Translators
     # Loads the appropriate desirialisation strategy based on
     # the content type
-    def self.load(content_type)
+    def self.lookup(content_type)
       translator = CONTENT_TYPES[content_type]
-      translator || (raise UnsupportedContentTypeException.new("Unsupported content type #{content_type}"))
+      translator || (raise Wrest::Exceptions::UnsupportedContentTypeException.new("Unsupported content type #{content_type}"))
     end
   end
 end
 
-require "#{WREST_ROOT}/wrest/translators/xml"
-require "#{WREST_ROOT}/wrest/translators/json"
-require "#{WREST_ROOT}/wrest/translators/content_types"
+require "#{WREST_ROOT}/wrest/components/translators/xml"
+require "#{WREST_ROOT}/wrest/components/translators/json"
+require "#{WREST_ROOT}/wrest/components/translators/content_types"

data/lib/wrest/{translators → components/translators}/content_types.rb

@@ -7,14 +7,14 @@
 # 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 Wrest::Components 
   module Translators
     # Maps content types to deserialisers
     CONTENT_TYPES = {
-      'application/xml' => Wrest::Translators::Xml,
-      'text/xml' => Wrest::Translators::Xml,
-      'application/json' => Wrest::Translators::Json,
-      'text/javascript' => Wrest::Translators::Json
+      'application/xml' => Wrest::Components::Translators::Xml,
+      'text/xml' => Wrest::Components::Translators::Xml,
+      'application/json' => Wrest::Components::Translators::Json,
+      'text/javascript' => Wrest::Components::Translators::Json
     }
   end
 end

data/lib/wrest/components/translators/json.rb

@@ -0,0 +1,22 @@
+# 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::Components::Translators
+  module Json
+    extend self
+
+    def deserialise(response)
+      ActiveSupport::JSON.decode(response.body)
+    end
+
+    def serialise(hash)
+      ActiveSupport::JSON.encode(hash)
+    end
+  end
+end