restfulie 0.5.0 → 0.6.0

data/Rakefile

@@ -5,7 +5,7 @@ require 'rake/gempackagetask'
 require 'spec/rake/spectask'
 
 GEM = "restfulie"
-GEM_VERSION = "0.5.0"
+GEM_VERSION = "0.6.0"
 SUMMARY = "Hypermedia aware resource based library in ruby (client side) and ruby on rails (server side)."
 AUTHOR = "Guilherme Silveira, Caue Guerra"
 EMAIL = "guilherme.silveira@caelum.com.br"
@@ -18,7 +18,7 @@ spec = Gem::Specification.new do |s|
   s.summary = SUMMARY
   s.require_paths = ['lib']
   s.files = FileList['lib/**/*.rb', '[A-Z]*'].to_a
-#  s.add_dependency("ratom", [">= 0.6.3"])
+  s.add_dependency("ratom", [">= 0.6.3"])
   # s.add_dependency("jeokkarak", [">= 1.0.3"])
 
   # s.add_dependency(%q<rubigen>, [">= 1.3.4"])

data/lib/restfulie/client/atom_media_type.rb

@@ -1,3 +1,20 @@
+#
+#  Copyright (c) 2009 Caelum - www.caelum.com.br/opensource
+#  All rights reserved.
+# 
+#  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 Restfulie
   
   # TODO break media type registering for DECODING and ENCODING appart, so we can have two files
@@ -23,7 +40,7 @@ module Restfulie
       # retrieves the nth element from an atom feed
       def [](position)
         
-        hash = entry[position].content.hash
+        hash = entry[position].content.internal_hash
         hash = hash.dup
         hash.delete("type")
         result = Restfulie::MediaType::DefaultMediaTypeDecoder.from_hash(hash)
@@ -36,7 +53,7 @@ module Restfulie
       private
       
       def add_links_to(result, entry)
-        links = entry.link.hash
+        links = entry.link.internal_hash
         links = [links] if links.kind_of? Hash
         self_definition = self_from(links)
         links << {:rel => "destroy", :method => "delete", :href => self_definition["href"]} unless self_definition.nil?

data/lib/restfulie/client/base.rb

@@ -1,3 +1,20 @@
+#
+#  Copyright (c) 2009 Caelum - www.caelum.com.br/opensource
+#  All rights reserved.
+# 
+#  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. 
+#
+
 class Hash
   def to_object(body)
     if keys.length>1
@@ -15,46 +32,34 @@ module Restfulie
 
   # will execute some action in a specific URI
   def self.at(uri)
-    Client::RequestExecution.new(nil).at uri
+    Client::RequestExecution.new(nil, nil).at uri
   end
-
+  
   module Client
-    module Base
+    module Config
+      BASIC_MAPPING = { :delete => Net::HTTP::Delete, :put => Net::HTTP::Put, :get => Net::HTTP::Get, :post => Net::HTTP::Post}
+      DEFAULTS = { :destroy => Net::HTTP::Delete, :delete => Net::HTTP::Delete, :cancel => Net::HTTP::Delete,
+                   :refresh => Net::HTTP::Get, :reload => Net::HTTP::Get, :show => Net::HTTP::Get, :latest => Net::HTTP::Get, :self => Net::HTTP::Get}
 
-      SELF_RETRIEVAL = [:latest, :refresh, :reload]
-      
-      # translates a response to an object
-      def from_response(res, invoking_object)
-        
-        return invoking_object if res.code=="304"
-        
-        raise UnsupportedContentType.new("unsupported content type '#{res.content_type}' '#{res.code}'") unless res.content_type=="application/xml"
-        
-        # TODO this method should use the RequestExecution process to parse the content type and body
-        # TODO add default html parser: do nothin
-
-        body = res.body
-        return {} if body.empty?
-        
-        hash = Hash.from_xml body
-        hash.to_object(body)
-        
+      def self.self_retrieval
+        [:latest, :refresh, :reload, :self]
+      end
+  
+      def self.requisition_method_for(overriden_option,name)
+        return BASIC_MAPPING[overriden_option.to_sym] if overriden_option
+        DEFAULTS[name.to_sym] || Net::HTTP::Post
       end
     
-      def requisition_method_for(overriden_option,name)
-        basic_mapping = { :delete => Net::HTTP::Delete, :put => Net::HTTP::Put, :get => Net::HTTP::Get, :post => Net::HTTP::Post}
-        defaults = {:destroy => Net::HTTP::Delete, :delete => Net::HTTP::Delete, :cancel => Net::HTTP::Delete,
-                    :refresh => Net::HTTP::Get, :reload => Net::HTTP::Get, :show => Net::HTTP::Get, :latest => Net::HTTP::Get, :self => Net::HTTP::Get}
+    end
+    
+    module Base
 
-        return basic_mapping[overriden_option.to_sym] if overriden_option
-        defaults[name.to_sym] || Net::HTTP::Post
-      end
-      
       def is_self_retrieval?(name)
         name = name.to_sym if name.kind_of? String
-        SELF_RETRIEVAL.include? name
+        Restfulie::Client::Config.self_retrieval.include? name
       end
-      
+    
     end
+    
   end
 end

data/lib/restfulie/client/cache.rb

@@ -0,0 +1,103 @@
+#
+#  Copyright (c) 2009 Caelum - www.caelum.com.br/opensource
+#  All rights reserved.
+# 
+#  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. 
+#
+
+# Basic cache implementation for restfulie.
+#
+# It uses the request headers and uri to store it in memory.
+# This cache might not be optimal for long running clients, which should use a memcached based one.
+# Use Restfulie.cache_provider to change the provider
+class Restfulie::BasicCache
+  
+  def put(url, req, response)
+    if Restfulie::Cache::Restrictions.may_cache?(req, response)
+      Restfulie.logger.debug "caching #{url} #{req} #{response}"
+      cache[key_for(url, req)] = response
+    end
+    response
+  end
+  
+  def get(url, req)
+    
+    response = cache[key_for(url, req)]
+    return nil if response.nil?
+    
+    if response.has_expired_cache?
+      remove(key_for(url, req))
+    else
+      Restfulie.logger.debug "RETURNING cache #{url} #{req}"
+      response
+    end
+    
+  end
+
+  # removes all elements from the cache
+  def clear
+    cache.clear
+  end
+  
+  private
+  
+  def remove(what)
+    @cache.delete(what)
+    nil
+  end
+  
+  def cache
+    @cache ||= {}
+  end
+  
+  def key_for(url, req)
+    [url, req.class]
+  end
+  
+end
+
+# Fake cache that does not cache anything
+# Use Restfulie.cache_provider = Restfulie::FakeCache.new
+class Restfulie::FakeCache
+  
+  def put(url, req, response)
+    response
+  end
+  
+  def get(url, req)
+  end
+  
+  def clear
+  end
+  
+end
+
+module Restfulie::Cache
+  module Restrictions
+    
+    class << self
+    
+      # checks whether this request verb and its cache headers allow caching
+      def may_cache?(request,response)
+        may_cache_method?(request) && response.may_cache?
+      end
+      
+      # only Post and Get requests are cacheable so far
+      def may_cache_method?(verb)
+        verb.kind_of?(Net::HTTP::Post) || verb.kind_of?(Net::HTTP::Get)
+      end
+
+    end
+    
+  end
+end

data/lib/restfulie/client/entry_point.rb

@@ -1,3 +1,20 @@
+#
+#  Copyright (c) 2009 Caelum - www.caelum.com.br/opensource
+#  All rights reserved.
+# 
+#  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 Restfulie
   module Client
     module Base
@@ -22,12 +39,12 @@ module Restfulie
       
       # retrieves a resource form a specific uri
       def from_web(uri, options = {})
-        RequestExecution.new(self).at(uri).get(options)
+        RequestExecution.new(self, nil).at(uri).get(options)
       end
 
       private
       def remote_post(content)
-        RequestExecution.new(self).at(entry_point_for.create.uri).post(content)
+        RequestExecution.new(self, nil).at(entry_point_for.create.uri).post(content)
       end
 
     end

data/lib/restfulie/client/extensions/http.rb

@@ -0,0 +1,116 @@
+#
+#  Copyright (c) 2009 Caelum - www.caelum.com.br/opensource
+#  All rights reserved.
+# 
+#  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 'time'
+
+# an extesion to http responses
+module Restfulie::Client::HTTPResponse
+  
+  attr_accessor :previous
+        
+  # determines if this response code was successful (according to http specs: 200~299)
+  def is_successful?
+    code.to_i >= 200 && code.to_i <= 299
+  end
+    
+  # determines if this response code was successful (according to http specs: 100~199)
+  def is_informational?
+    code.to_i >= 100 && code.to_i <= 199
+  end
+    
+  # determines if this response code was successful (according to http specs: 300~399)
+  def is_redirection?
+    code.to_i >= 300 && code.to_i <= 399
+  end
+    
+  # determines if this response code was successful (according to http specs: 400~499)
+  def is_client_error?
+    code.to_i >= 400 && code.to_i <= 499
+  end
+    
+  # determines if this response code was successful (according to http specs: 500~599)
+  def is_server_error?
+    code.to_i >= 500 && code.to_i <= 599
+  end
+  
+  def etag
+    self['Etag']
+  end
+
+  def last_modified
+    self['Last-Modified']
+  end
+  
+end
+  
+module Restfulie::Client::HTTPResponse
+
+  def cache_max_age
+    val = header_value_from('Cache-control', /^\s*max-age=(\d+)/)
+    if val
+      val.to_i
+    else
+      0
+    end
+  end
+  
+  def header_value_from(header, expression)
+    h = value_for(get_fields(header)[0], expression)
+    return nil if h.nil?
+    h.match(expression)[1]
+  end
+  
+  def has_expired_cache?
+    return true if self['Date'].nil?
+    Time.now > Time.rfc2822(self['Date']) + cache_max_age.seconds
+  end
+
+  # checks if the header's max-age is available and no no-store if available.
+  def may_cache?
+    may_cache_field?(get_fields('Cache-control'))
+  end
+  
+  def may_cache_field?(field)
+    return false if field.nil?
+    
+    if field.kind_of? Array
+      field.each do |f|
+        return false if !may_cache_field?(f)
+      end
+      return true
+    end
+
+    max_age_header = value_for(field, /^max-age=(\d+)/)
+    return false if max_age_header.nil?
+    max_age = max_age_header[1]
+    
+    return false if value_for(field, /^no-store/)
+    
+    true
+  end
+
+  # extracts the header value for an specific expression, which can be located at the start or in the middle
+  # of the expression
+  def value_for(value, expression)
+    value.split(",").find { |obj| obj.strip =~ expression }
+  end
+    
+end
+
+class Net::HTTPResponse
+  include Restfulie::Client::HTTPResponse
+end

data/lib/restfulie/client/helper.rb

@@ -1,3 +1,20 @@
+#
+#  Copyright (c) 2009 Caelum - www.caelum.com.br/opensource
+#  All rights reserved.
+# 
+#  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 Restfulie
   module Client
     module Helper

data/lib/restfulie/client/instance.rb

@@ -1,134 +1,158 @@
-module Restfulie
-  module Client
-    module Instance
+#
+#  Copyright (c) 2009 Caelum - www.caelum.com.br/opensource
+#  All rights reserved.
+# 
+#  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 Restfulie::Client::Instance
       
-      # list of possible states to access
-      def _possible_states
-        @_possible_states ||= {}
-      end
-
-      # which content-type generated this data
-      attr_accessor :_came_from
-      
-      def invoke_remote_transition(name, options, block)
-
-        method = self.class.requisition_method_for options[:method], name
-
-        state = self._possible_states[name]
-        url = URI.parse(state["href"] || state[:href])
-        req = method.new(url.path)
-        req.body = options[:data] if options[:data]
-        add_request_headers(req, name)
-        
-        response = Net::HTTP.new(url.host, url.port).request(req)
+  # list of possible states to access
+  def existing_relations
+    @existing_relations ||= {}
+  end
 
-        return block.call(response) if block
-        return response unless method == Net::HTTP::Get
-        self.class.from_response response, self
-      end
-      
-      private
-      def add_request_headers(req, name)
-        req.add_field("Accept", "application/xml") if self._came_from == :xml
-        req.add_field("If-None-Match", self.etag) if self.class.is_self_retrieval?(name) && self.respond_to?(:etag)
-        req.add_field("If-Modified-Since", self.last_modified) if self.class.is_self_retrieval?(name) && self.respond_to?(:last_modified)
+  # which content-type generated this data
+  attr_reader :_came_from
+  
+  # prepares a new request
+  def request
+    Restfulie::Client::RequestExecution.new(self.class, self)
+  end
+  
+  # parse arguments from a transition invocation (or relation)
+  # it will receive either zero, one or two args, if there are two args, return them
+  # if there is one hash arg, its the options, add a data = nil
+  # if there is one arg (not a hash), its the data, add a options = {}
+  # if there are no args, data is nil and options = {}
+  def parse_args_from_transition(args)
+    data = nil
+    if args.nil? || args.size==0
+      options = {}
+    elsif args.size==1
+      if args[0].kind_of?(Hash)
+        options = args[0]
+      else
+        data = args[0]
+        options = {}
       end
+    elsif args.size==2
+      data = args[0]
+      options = args[1] || {}
+    end
+    [data, options]
+  end
+  
+  def invoke_remote_transition(name, args, block = nil)
+    
+    data, options = parse_args_from_transition(args)
+    
+    method = Restfulie::Client::Config.requisition_method_for options[:method], name
+    state = self.existing_relations[name]
+    
+    request = Restfulie::Client::RequestExecution.new(self.class, self).at(state["href"] || state[:href]).with(options[:headers])
+    request.do method, name, data
 
-      public
+  end
 
-  
-      # inserts all links from this object as can_xxx and xxx methods
-      def add_transitions(links)
-
-        links.each do |t|
-          self._possible_states[t["rel"] || t[:rel]] = t
-          self.add_state(t)
-        end
-        self.extend Restfulie::Client::State
-      end
+  # inserts all links from this object as can_xxx and xxx methods
+  def add_transitions(links)
+    links.each do |t|
+      self.existing_relations[t["rel"] || t[:rel]] = t
+      self.add_state(t)
+    end
+    self.extend Restfulie::Client::State
+  end
 
+  # adds the specific information for one state change or related resource
+  def add_state(transition)
+    name = transition["rel"] || transition[:rel]
+  
+    # TODO: wrong, should be instance_eval
+    self.class.module_eval do
     
-      def add_state(transition)
-        name = transition["rel"] || transition[:rel]
-      
-        # TODO: wrong, should be instance_eval
-        self.class.module_eval do
-        
-          def temp_method(options = {}, &block)
-            self.invoke_remote_transition(Restfulie::Client::Helper.current_method, options, block)
-          end
-        
-          alias_method name, :temp_method
-          undef :temp_method
-        end
-      end  
-
-      # returns a list of extended fields for this instance.
-      # extended fields are those unknown to this model but kept in a hash
-      # to allow forward-compatibility.
-      def extended_fields
-        @hash ||= {}
-        @hash
+      def temp_method(*args, &block)
+        self.invoke_remote_transition(Restfulie::Client::Helper.current_method, args, block)
       end
+    
+      alias_method name, :temp_method
+      undef :temp_method
+    end
+  end  
+
+  # returns a list of extended fields for this instance.
+  # extended fields are those unknown to this model but kept in a hash
+  # to allow forward-compatibility.
+  def extended_fields
+    @extended_fields ||= {}
+    @extended_fields
+  end
 
-      def method_missing(name, *args)
-        name = name.to_s if name.kind_of? Symbol
-
-        if name[-1,1] == "="
-          extended_fields[name.chop] = args[0] 
-        elsif name[-1,1] == "?"
-          found = extended_fields[name.chop]
-          return super(name,args) if found.nil?
-          parse(found)
-        else
-          found = extended_fields[name]
-          return super(name,args) if found.nil?
-          parse(transform(found))
-        end
+  def method_missing(name, *args)
+    name = name.to_s if name.kind_of? Symbol
+
+    if name[-1,1] == "="
+      extended_fields[name.chop] = args[0] 
+    elsif name[-1,1] == "?"
+      found = extended_fields[name.chop]
+      return super(name,args) if found.nil?
+      parse(found)
+    else
+      found = extended_fields[name]
+      return super(name,args) if found.nil?
+      parse(transform(found))
+    end
 
-      end
+  end
 
-      # TODO test this guy
-      def respond_to?(sym)
-        extended_fields[sym.to_s].nil? ? super(sym) : true
-      end
+  def respond_to?(sym)
+    extended_fields[sym.to_s].nil? ? super(sym) : true
+  end
 
-      # redefines attribute definition allowing the invocation of method_missing
-      # when an attribute does not exist
-      def attributes=(values)
-        values.each do |key, value|
-          unless attributes.include? key
-            method_missing("#{key}=", value)
-            values.delete key
-          end
-        end
-        super(values)
+  # redefines attribute definition allowing the invocation of method_missing
+  # when an attribute does not exist
+  def attributes=(values)
+    values.each do |key, value|
+      unless attributes.include? key
+        method_missing("#{key}=", value)
+        values.delete key
       end
+    end
+    super(values)
+  end
 
 
-      # serializes the extended fields with the existing fields
-      def to_xml(options={})
-        super(options) do |xml|
-          extended_fields.each do |key,value|
-            xml.tag! key, value
-          end
-        end
+  # serializes the extended fields with the existing fields
+  def to_xml(options={})
+    super(options) do |xml|
+      extended_fields.each do |key,value|
+        xml.tag! key, value
       end
+    end
+  end
 
-      private
-      
-      # transforms a value in a custom hash
-      def transform(value)
-        return CustomHash.new(value) if value.kind_of?(Hash) || value.kind_of?(Array)
-        value
-      end
-      
-      def parse(val)
-        raise "undefined method: '#{val}'" if val.nil?
-        val
-      end
+  private
+  
+  # transforms a value in a custom hash
+  def transform(value)
+    return CustomHash.new(value) if value.kind_of?(Hash) || value.kind_of?(Array)
+    value
+  end
+  
+  def parse(val)
+    raise "undefined method: '#{val}'" if val.nil?
+    val
+  end
 
 
-    end
-  end
 end