kaiwren-wrest 0.0.6 → 0.0.8

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

@@ -7,20 +7,17 @@
 # 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 'xmlsimple'
+module Wrest
+  module Components::Translators
+    module Xml
+      extend self
 
-module Wrest::Components::Translators
-  module Xml
-    extend self
+      def deserialise(response)
+        ActiveSupport::XmlMini.parse(response.body)
+      end
 
-    def deserialise(response)
-      XmlSimple.xml_in(
-      response.body,
-      'keeproot'  => true
-      )
-    end
-
-    def serialise(hash)
+      def serialise(hash)
+      end
     end
   end
 end

data/lib/wrest/core_ext/hash/conversions.rb

@@ -22,7 +22,7 @@ module Wrest
         # Yes, the name is misleading in that respect. However, one 
         # hopes the absence of an exclamation mark will increase clarity.
         #
-        # Uses include mutating the hash produced by xml-simple
+        # Uses include mutating the hash produced by deserialising xml
         # by using the meta data in the hash to type cast values.
         # 
         # Example:

data/lib/wrest/core_ext/string/conversions.rb

@@ -14,8 +14,8 @@ module Wrest
       module Conversions
 
         # A convenience method equivalent to Wrest::Uri.new(string)
-        def to_uri
-          Wrest::Uri.new(self)
+        def to_uri(options = {})
+          Wrest::Uri.new(self, options)
         end
       end
     end

data/lib/wrest/http.rb

@@ -0,0 +1,24 @@
+# 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:
+
+  # Contains all HTTP protocol related classes such as
+  # Get, Post, Request, Response etc.
+  module Http
+  end
+end
+
+require "#{WREST_ROOT}/wrest/http/response"
+require "#{WREST_ROOT}/wrest/http/request"
+require "#{WREST_ROOT}/wrest/http/get"
+require "#{WREST_ROOT}/wrest/http/put"
+require "#{WREST_ROOT}/wrest/http/post"
+require "#{WREST_ROOT}/wrest/http/delete"
+require "#{WREST_ROOT}/wrest/http/options"

data/lib/wrest/http/delete.rb

@@ -0,0 +1,23 @@
+# 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::Http
+  class Delete < Request
+    def initialize(wrest_uri, parameters = {}, headers = {}, options = {})
+      super(
+            wrest_uri, 
+            Net::HTTP::Delete, 
+            parameters,
+            nil,
+            headers,
+            options
+          )
+    end
+  end
+end

data/lib/wrest/http/get.rb

@@ -0,0 +1,23 @@
+# 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::Http
+  class Get < Request
+    def initialize(wrest_uri, parameters = {}, headers = {}, options = {})
+      super(
+            wrest_uri, 
+            Net::HTTP::Get, 
+            parameters,
+            nil,
+            headers,
+            options
+          )
+    end
+  end
+end

data/lib/wrest/http/options.rb

@@ -0,0 +1,23 @@
+# 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::Http
+  class Options < Request
+    def initialize(wrest_uri, options = {})
+      super(
+            wrest_uri, 
+            Net::HTTP::Options, 
+            {},
+            nil,
+            {},
+            options
+          )
+    end
+  end
+end

data/lib/wrest/http/post.rb

@@ -0,0 +1,23 @@
+# 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::Http
+  class Post < Request
+    def initialize(wrest_uri, body = '', headers = {}, parameters = {}, options = {})
+      super(
+        wrest_uri,
+        Net::HTTP::Post,
+        parameters,
+        body,
+        headers,
+        options
+      )
+    end
+  end
+end

data/lib/wrest/http/put.rb

@@ -0,0 +1,23 @@
+# 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::Http
+  class Put < Request
+    def initialize(wrest_uri, body = '', headers = {}, parameters = {}, options = {})
+      super(
+        wrest_uri,
+        Net::HTTP::Put,
+        parameters,
+        body,
+        headers,
+        options
+      )
+    end
+  end
+end

data/lib/wrest/http/request.rb

@@ -0,0 +1,48 @@
+# 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::Http
+  class Request
+    attr_reader :http_request, :uri, :body, :headers, :username, :password
+    def initialize(wrest_uri, http_request_klass, parameters = {}, body = nil, headers = {}, options = {})
+      @uri = wrest_uri
+      @headers = headers.stringify_keys
+      @http_request = http_request_klass.new(parameters.empty? ? wrest_uri.full_path : "#{wrest_uri.full_path}?#{parameters.to_query}", @headers)
+      @body = body
+      @options = options
+      @username = options[:username]
+      @password = options[:password]
+    end
+
+    # Makes a request and returns a Wrest::Http::Response. 
+    # Data about the request is and logged to Wrest.logger
+    def invoke
+      response = nil
+
+      prefix = "#{http_request.method} #{http_request.hash}"
+      http_request.basic_auth username, password
+
+      Wrest.logger.debug "--> (#{prefix}) #{@uri.protocol}://#{@uri.host}:#{@uri.port}#{@http_request.path}"
+      time = Benchmark.realtime { response = Wrest::Http::Response.new( http.request(@http_request, @body) ) }
+      Wrest.logger.debug "<-- (#{prefix}) %d %s (%d bytes %.2fs)" % [response.code, response.message, response.body ? response.body.length : 0, time]
+
+      response
+    end
+
+    private
+    def http
+      http = Net::HTTP.new(@uri.host, @uri.port)
+      if @uri.https?
+        http.use_ssl     = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      end
+      http
+    end
+  end
+end

data/lib/wrest/http/response.rb

@@ -0,0 +1,44 @@
+# 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:
+  module Http #:nodoc:
+    # Decorates a response providing support for deserialisation.
+    #
+    # The following methods are also available (unlisted by rdoc because they're forwarded):
+    #
+    # <tt>:@Http_response,  :code, :message, :body, :Http_version,
+    # :[], :content_length, :content_type, :each_header, :each_name, :each_value, :fetch,
+    # :get_fields, :key?, :type_params</tt>
+    #
+    # They behave exactly like their Net::HttpResponse equivalents.
+    class Response
+      extend Forwardable
+      def_delegators  :@http_response,  :code, :message, :body, :Http_version,
+              :[], :content_length, :content_type, :each_header, :each_name, :each_value, :fetch,
+              :get_fields, :key?, :type_params
+
+      def initialize(http_response)
+        @http_response = http_response
+      end
+
+      def deserialise
+        deserialise_using(Wrest::Components::Translators.lookup(@http_response.content_type))
+      end
+
+      def deserialise_using(translator)
+        translator.deserialise(@http_response)
+      end
+
+      def headers
+        @http_response.to_hash
+      end
+    end
+  end
+end

data/lib/wrest/resource/base.rb

@@ -12,61 +12,88 @@ module Wrest::Resource #:nodoc:
   # It is a REST client targetted at Rails REST apps.
   class Base
     include Wrest::Components::AttributesContainer
+    include Wrest::Components::AttributesContainer::Typecaster
 
-    has_attributes  :id
+    always_has      :id
     typecast        :id => as_integer
     attr_reader     :attributes
-    
+
+    def ==(other)
+      return true if self.equal?(other)
+      return false unless other.class == self.class
+      return self.attributes == other.attributes
+    end
+
+    def hash
+      id.hash
+    end
+
+    def to_xml(options={})
+      attributes.to_xml({:root => self.class.resource_name.gsub('_', '-')}.merge(options))
+    end
+
     class << self
       def inherited(klass)
         klass.set_resource_name klass.name
       end
-      
+
       # Allows the resource name to be configured and creates
-      # a getter method for it. 
+      # a getter method for it.
       # This is a useful feature when using anonymous classes like
       # we often do while writing tests.
       # By default, the resource name is set to the name of the class.
       def set_resource_name(resource_name)
-        self.class_eval "def self.resource_name; '#{resource_name}';end"
+        self.class_eval "def self.resource_name; '#{resource_name.underscore}';end"
       end
-      
+
       # Allows the host url at which the resource is found to be configured
-      # and creates a getter method for it. 
+      # and creates a getter method for it.
       # For example in the url
       #  http://localhost:3000/users/1/settings
-      # you would set 
+      # you would set
       #  http://localhost:3000
       # as the host url.
       def set_host(host)
         self.class_eval "def self.host; '#{host}';end"
       end
-      
-      def set_redirect_handler(method_object)
+
+      def set_default_format(format)
+        self.class_eval "def self.default_format; '#{format.to_s}';end"
       end
-      
-      def resource_path
-        @resource_path ||= "/#{resource_name.underscore.pluralize}"
+
+      def set_redirect_handler(method_object)
       end
 
-      def resource_url
-        "#{host}#{resource_path}"
+      def resource_collection_name
+        @resource_collection_name ||= "#{resource_name.underscore.pluralize}"
       end
-      
-      def find_all
+
+      def find_one_uri_template
+        @find_one_template ||= Wrest::UriTemplate.new(':host/:resource_collection_name/:id.:format')
       end
 
       def find(id)
-        response_hash = "#{resource_url}/#{id}".to_uri.get.deserialise
-        resource_type = response_hash.keys.first
-        if(resource_type.underscore.camelize == self.name)
-          self.new(response_hash[resource_type].first)
-        else
-          response_hash
-        end
+        response = find_one_uri_template.to_uri(
+          :host => host,
+          :resource_collection_name => resource_collection_name,
+          :id => id,
+          :format => default_format
+        ).get
+        self.new(response.deserialise.mutate_using(
+          Wrest::Components::Mutators.chain(:xml_mini_type_caster, :camel_to_snake_case)
+        ).shift.last)
       end
 
-      def objectify(hash)
+      def create(attributes = {})
+        response = Wrest::UriTemplate.new(':host/:resource_collection_name.:format').to_uri(
+          :host => host,
+          :resource_collection_name => resource_collection_name,
+          :format => default_format
+        ).post(self.new(attributes).to_xml, 'Content-Type' => "application/#{default_format}")
+
+        self.new(response.deserialise.mutate_using(
+          Wrest::Components::Mutators.chain(:xml_mini_type_caster, :camel_to_snake_case)
+        ).shift.last)
       end
     end
   end

data/lib/wrest/resource/state.rb

@@ -0,0 +1,6 @@
+module Wrest
+  module Resource
+    class State
+    end
+  end
+end

data/lib/wrest/uri.rb

@@ -11,10 +11,44 @@ module Wrest #:nodoc:
   # Wrest::Uri provides a simple api for
   # REST calls. String#to_uri is a convenience
   # method to build a Wrest::Uri from a string url.
+  # Note that a Wrest::Uri is immutable.
+  #
+  # Basic HTTP Authentication is supported.
+  # Example:
+  #  "http://kaiwren:fupuppies@coathangers.com/portal/1".to_uri
+  #  "http://coathangers.com/portal/1".to_uri(:username => 'kaiwren', :password => 'fupuppies')
+  # 
+  # The second form is preferred as it can handle passwords with special characters like ^ and @
+  #
+  # You can find examples that use real APIs (like delicious) under the wrest/examples directory.
   class Uri
-    attr_reader :uri
-    def initialize(uri_string)
+    attr_reader :uri, :username, :password
+    def initialize(uri_string, options = {})
+      @options = options
+      @uri_string = uri_string.clone
       @uri = URI.parse(uri_string)
+      @options = options
+      @username = (@options[:username] ||= @uri.user)
+      @password = (@options[:password] ||= @uri.password)
+    end
+    
+    # Build a new Wrest::Uri by appending _path_ to
+    # the current uri. If the original Wrest::Uri
+    # has a username and password, that will be
+    # copied to the new Wrest::Uri as well.
+    #
+    # Example:
+    #  uri = "https://localhost:3000/v1".to_uri
+    #  uri['/oogas/1'].get
+    #
+    # To change the username and password on the new
+    # instance, simply pass them as an options map.
+    #
+    # Example:
+    #  uri = "https://localhost:3000/v1".to_uri(:username => 'foo', :password => 'bar')
+    #  uri['/oogas/1', {:username => 'meh', :password => 'baz'}].get
+    def [](path, options = nil)
+      Uri.new(@uri_string+path, options || @options)
     end
     
     def eql?(other)
@@ -23,52 +57,74 @@ module Wrest #:nodoc:
     
     def ==(other)
       return false if other.class != self.class
-      return other.uri == self.uri
+      return other.uri == self.uri && self.username == other.username && self.password == other.password
     end
     
     def hash
-      self.uri.hash + 20090423
+      @uri.hash + @username.hash + @password.hash + 20090423
     end
     
-    # Make a HTTP get request to this URI.
-    # Remember to escape the parameter strings using URI.escape 
+    # Make a GET request to this URI. This is a convenience API
+    # that creates a Wrest::Http::Get, executes it and returns a Wrest::Http::Response.
+    #
+    # Remember to escape all parameter strings if necessary, using URI.escape
     def get(parameters = {}, headers = {})
-      do_request 'get', parameters.empty? ? @uri.request_uri : "#{@uri.request_uri}?#{parameters.to_query}", headers.stringify_keys
+      Http::Get.new(self, parameters, headers, @options).invoke
     end
 
-    def put(body = '', headers = {})
-      do_request 'put', @uri.request_uri, body.to_s, headers.stringify_keys
+    # Make a PUT request to this URI. This is a convenience API
+    # that creates a Wrest::Http::Put, executes it and returns a Wrest::Http::Response.
+    #
+    # Remember to escape all parameter strings if necessary, using URI.escape
+    def put(body = '', headers = {}, parameters = {})
+      Http::Put.new(self, body.to_s, headers, parameters, @options).invoke
     end
 
-    def post(body = '', headers = {})
-      do_request 'post', @uri.request_uri, body.to_s, headers.stringify_keys
+    # Makes a POST request to this URI. This is a convenience API
+    # that creates a Wrest::Http::Post, executes it and returns a Wrest::Http::Response.
+    #
+    # Remember to escape all parameter strings if necessary, using URI.escape
+    def post(body = '', headers = {}, parameters = {})
+      Http::Post.new(self, body.to_s, headers, parameters, @options).invoke
     end
 
+    # Makes a DELETE request to this URI. This is a convenience API
+    # that creates a Wrest::Http::Delete, executes it and returns a Wrest::Http::Response.
+    #
+    # Remember to escape all parameter strings if necessary, using URI.escape
     def delete(parameters = {}, headers = {})
-      do_request 'delete', parameters.empty? ? @uri.request_uri : "#{@uri.request_uri}?#{parameters.to_query}", headers.stringify_keys
+      Http::Delete.new(self, parameters, headers, @options).invoke
     end
-    
-    def do_request(method, url, *args)
-      response = nil
-
-      Wrest.logger.info  "#{method} -> #{url}"
-      time = Benchmark.realtime { response = Wrest::Response.new(http.send(method, url, *args)) }
-      Wrest.logger.info "--> %d %s (%d %.2fs)" % [response.code, response.message, response.body ? response.body.length : 0, time]
 
-      response
+    # Makes an OPTIONS request to this URI. This is a convenience API
+    # that creates a Wrest::Http::Options, executes it and returns the Wrest::Http::Response.
+    def options
+      Http::Options.new(self, @options).invoke
     end
-    
+
     def https?
       @uri.is_a?(URI::HTTPS)
     end
-
-    def http
-      http = Net::HTTP.new(@uri.host, @uri.port)
-      if https?
-        http.use_ssl     = true
-        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
-      end
-      http
+    
+    # Provides the full path of a request.
+    # For example, for
+    #  http://localhost:3000/demons/1/chi?sort=true
+    # this would return
+    #  /demons/1/chi?sort=true
+    def full_path
+      uri.request_uri
+    end
+    
+    def protocol
+      uri.scheme
+    end
+    
+    def host
+      uri.host
+    end
+    
+    def port
+      uri.port
     end
   end
 end