spark_api 1.0.0

data/lib/spark_api/paginate.rb

@@ -0,0 +1,109 @@
+require 'will_paginate/collection'
+
+# =Pagination for api resource collections
+# Will paginate adapter for the api client.  Utilizes the same interface as will paginate and returns the 
+# same WillPaginate::Collection for finder results.
+module SparkApi
+  module Paginate
+    
+    DEFAULT_PAGE_SIZE = 25
+    
+    # == Replacement hook for will_paginate's class method
+    # Does a best effort to mimic the will_paginate method of same name.  All arguments are
+    # passed on to the finder method except the special keys for the options hash listed below.
+    #
+    # == Special parameters for paginating finders
+    # * <tt>:page</tt> -- REQUIRED, but defaults to 1 if false or nil
+    # * <tt>:per_page</tt> -- defaults to <tt>CurrentModel.per_page</tt> (which is 25 if not overridden)
+    # * <tt>:finder</tt> -- name of the finder used (default: "get").  This needs to be a class finder method on the class
+    def paginate(*args)
+      options = args.last.is_a?(::Hash) ? args.pop : {}
+      page = options.delete(:page) || 1
+      items_per_page = options.delete(:per_page) || self.per_page
+      finder = (options.delete(:finder) || 'get').to_s
+      page_options = {
+        "_pagination" => 1,
+        "_limit" => items_per_page,
+        "_page" => page
+      }
+      options.merge!(page_options)
+      args << options
+      collection = send(finder,*args)
+    end
+    
+    # == Instanciate class instances from array of hash representations.  
+    # Needs to be called by all finders that would like to support paging.  Takes the hash result 
+    # set from the request layer and instanciates instances of the class called for the finder.
+    #
+    # * result_array -- the results object returned from the api request layer.  An array of hashes.
+    # 
+    # :returns:
+    #   An array of class instances for the Class of the calling finder
+    def collect(result_array)
+      
+      # when conducting a count (pagination=count), the result_array is not an array
+      # in those cases, simply return the Fixnum
+      return result_array unless result_array.kind_of? Array
+      
+      collection = result_array.collect { |item| new(item)}
+      result_array.replace(collection)
+      result_array
+    end
+    
+    # Default per_page limit set on all models.  Override this method in the model such ala the 
+    # will_paginate gem to change
+    def per_page
+      DEFAULT_PAGE_SIZE
+    end
+    
+    
+  end
+
+  # ==Paginate Api Responses
+  # Module used by the request layer to decorate the response's results array with paging support.
+  # Pagination only happens if the response includes the pagination information as specified by the 
+  # API.
+  module PaginateResponse
+    attr_accessor :results
+    def method_missing(method_symbol, *arguments)
+      if results.respond_to?(method_symbol)
+        arguments.empty? ? self.results.send(method_symbol) : self.results.send(method_symbol, arguments)
+      else
+        super
+      end
+    end
+  end
+    
+  # ==Pagination Helpers
+  # Helpers to create the pagination collection
+  module PaginateHelper
+    # ==Enable pagination
+    # * results -- array of hashes representing api resources
+    # * paging_hash -- the pagination response information from the api representing paging state.
+    # 
+    # :returns:
+    #   The result set decorated as a WillPaginate::Collection
+    def paginate_response(results, paging_hash)
+      pager = Pagination.new(paging_hash)
+      paged_results = WillPaginate::Collection.create(pager.current_page, pager.page_size, pager.total_rows) do |p|
+        p.replace(results)
+      end
+      paged_results.extend PaginateResponse
+      paged_results.results = results
+      paged_results
+    end
+  end
+
+  # ==Pagination
+  #   Simple class representing the API's pagination response object
+  class Pagination
+    attr_accessor :total_rows, :page_size, :total_pages, :current_page
+    def initialize(hash)
+      @total_rows     = hash["TotalRows"]
+      @page_size      = hash["PageSize"]
+      @total_pages    = hash["TotalPages"]
+      @current_page   = hash["CurrentPage"]
+    end
+  end
+  
+end

data/lib/spark_api/paginate.rb~

@@ -0,0 +1,109 @@
+require 'will_paginate/collection'
+
+# =Pagination for api resource collections
+# Will paginate adapter for the api client.  Utilizes the same interface as will paginate and returns the 
+# same WillPaginate::Collection for finder results.
+module FlexmlsApi
+  module Paginate
+    
+    DEFAULT_PAGE_SIZE = 25
+    
+    # == Replacement hook for will_paginate's class method
+    # Does a best effort to mimic the will_paginate method of same name.  All arguments are
+    # passed on to the finder method except the special keys for the options hash listed below.
+    #
+    # == Special parameters for paginating finders
+    # * <tt>:page</tt> -- REQUIRED, but defaults to 1 if false or nil
+    # * <tt>:per_page</tt> -- defaults to <tt>CurrentModel.per_page</tt> (which is 25 if not overridden)
+    # * <tt>:finder</tt> -- name of the finder used (default: "get").  This needs to be a class finder method on the class
+    def paginate(*args)
+      options = args.last.is_a?(::Hash) ? args.pop : {}
+      page = options.delete(:page) || 1
+      items_per_page = options.delete(:per_page) || self.per_page
+      finder = (options.delete(:finder) || 'get').to_s
+      page_options = {
+        "_pagination" => 1,
+        "_limit" => items_per_page,
+        "_page" => page
+      }
+      options.merge!(page_options)
+      args << options
+      collection = send(finder,*args)
+    end
+    
+    # == Instanciate class instances from array of hash representations.  
+    # Needs to be called by all finders that would like to support paging.  Takes the hash result 
+    # set from the request layer and instanciates instances of the class called for the finder.
+    #
+    # * result_array -- the results object returned from the api request layer.  An array of hashes.
+    # 
+    # :returns:
+    #   An array of class instances for the Class of the calling finder
+    def collect(result_array)
+      
+      # when conducting a count (pagination=count), the result_array is not an array
+      # in those cases, simply return the Fixnum
+      return result_array unless result_array.kind_of? Array
+      
+      collection = result_array.collect { |item| new(item)}
+      result_array.replace(collection)
+      result_array
+    end
+    
+    # Default per_page limit set on all models.  Override this method in the model such ala the 
+    # will_paginate gem to change
+    def per_page
+      DEFAULT_PAGE_SIZE
+    end
+    
+    
+  end
+
+  # ==Paginate Api Responses
+  # Module used by the request layer to decorate the response's results array with paging support.
+  # Pagination only happens if the response includes the pagination information as specified by the 
+  # API.
+  module PaginateResponse
+    attr_accessor :results
+    def method_missing(method_symbol, *arguments)
+      if results.respond_to?(method_symbol)
+        arguments.empty? ? self.results.send(method_symbol) : self.results.send(method_symbol, arguments)
+      else
+        super
+      end
+    end
+  end
+    
+  # ==Pagination Helpers
+  # Helpers to create the pagination collection
+  module PaginateHelper
+    # ==Enable pagination
+    # * results -- array of hashes representing api resources
+    # * paging_hash -- the pagination response information from the api representing paging state.
+    # 
+    # :returns:
+    #   The result set decorated as a WillPaginate::Collection
+    def paginate_response(results, paging_hash)
+      pager = Pagination.new(paging_hash)
+      paged_results = WillPaginate::Collection.create(pager.current_page, pager.page_size, pager.total_rows) do |p|
+        p.replace(results)
+      end
+      paged_results.extend PaginateResponse
+      paged_results.results = results
+      paged_results
+    end
+  end
+
+  # ==Pagination
+  #   Simple class representing the API's pagination response object
+  class Pagination
+    attr_accessor :total_rows, :page_size, :total_pages, :current_page
+    def initialize(hash)
+      @total_rows     = hash["TotalRows"]
+      @page_size      = hash["PageSize"]
+      @total_pages    = hash["TotalPages"]
+      @current_page   = hash["CurrentPage"]
+    end
+  end
+  
+end

data/lib/spark_api/primary_array.rb

@@ -0,0 +1,29 @@
+module SparkApi
+  class PrimaryArray < Array
+    
+    def primary
+      find_primary
+    end
+
+    private 
+    
+    # This is a very simplistic but reliable implementation.
+    def find_primary
+      self.each do |arg|
+        if arg.primary?
+          return arg
+        end
+      end
+      nil
+    end
+  end
+  
+  #=== Primary: interface to implement for elements that are added to a "PrimaryArray" collection
+  module Primary
+    # Return true if the element is the primary resource in a collection.
+    # Default implementation looks for a "Primary" attribute
+    def primary?
+      @attributes.key?("Primary") && self.Primary == true
+    end
+  end
+end

data/lib/spark_api/primary_array.rb~

@@ -0,0 +1,29 @@
+module FlexmlsApi
+  class PrimaryArray < Array
+    
+    def primary
+      find_primary
+    end
+
+    private 
+    
+    # This is a very simplistic but reliable implementation.
+    def find_primary
+      self.each do |arg|
+        if arg.primary?
+          return arg
+        end
+      end
+      nil
+    end
+  end
+  
+  #=== Primary: interface to implement for elements that are added to a "PrimaryArray" collection
+  module Primary
+    # Return true if the element is the primary resource in a collection.
+    # Default implementation looks for a "Primary" attribute
+    def primary?
+      @attributes.key?("Primary") && self.Primary == true
+    end
+  end
+end

data/lib/spark_api/request.rb

@@ -0,0 +1,96 @@
+require 'cgi'
+
+module SparkApi
+  # HTTP request wrapper.  Performs all the api session mumbo jumbo so that the models don't have to.
+  module Request
+    # Perform an HTTP GET request
+    # 
+    # * path - Path of an api resource, excluding version and endpoint (domain) information
+    # * options - Resource request options as specified being supported via and api resource
+    # :returns:
+    #   Hash of the json results as documented in the api.
+    # :raises:
+    #   SparkApi::ClientError or subclass if the request failed.
+    def get(path, options={})
+      request(:get, path, nil, options)
+    end
+
+    # Perform an HTTP POST request
+    # 
+    # * path - Path of an api resource, excluding version and endpoint (domain) information
+    # * body - Hash for post body data
+    # * options - Resource request options as specified being supported via and api resource
+    # :returns:
+    #   Hash of the json results as documented in the api.
+    # :raises:
+    #   SparkApi::ClientError or subclass if the request failed.
+    def post(path, body={}, options={})
+      request(:post, path, body, options)
+    end
+
+    # Perform an HTTP PUT request
+    # 
+    # * path - Path of an api resource, excluding version and endpoint (domain) information
+    # * body - Hash for post body data
+    # * options - Resource request options as specified being supported via and api resource
+    # :returns:
+    #   Hash of the json results as documented in the api.
+    # :raises:
+    #   SparkApi::ClientError or subclass if the request failed.
+    def put(path, body={}, options={})
+      request(:put, path, body, options)
+    end
+
+    # Perform an HTTP DELETE request
+    # 
+    # * path - Path of an api resource, excluding version and endpoint (domain) information
+    # * options - Resource request options as specified being supported via and api resource
+    # :returns:
+    #   Hash of the json results as documented in the api.
+    # :raises:
+    #   SparkApi::ClientError or subclass if the request failed.
+    def delete(path, options={})
+      request(:delete, path, nil, options)
+    end
+    
+    private
+
+    # Perform an HTTP request (no data)
+    def request(method, path, body, options)
+      unless authenticated?
+        authenticate
+      end
+      attempts = 0
+      begin
+        request_opts = {}
+        request_opts.merge!(options)
+        post_data = body.nil? ? nil : {"D" => body }.to_json
+        request_path = "/#{version}#{path}"
+        start_time = Time.now
+        SparkApi.logger.debug("#{method.to_s.upcase} Request:  #{request_path}")
+        if post_data.nil?
+          response = authenticator.request(method, request_path, nil, request_opts)
+        else
+          SparkApi.logger.debug("#{method.to_s.upcase} Data:   #{post_data}")
+          response = authenticator.request(method, request_path, post_data, request_opts)
+        end
+        request_time = Time.now - start_time
+        SparkApi.logger.info("[#{(request_time * 1000).to_i}ms] Api: #{method.to_s.upcase} #{request_path}")
+      rescue PermissionDenied => e
+        if(ResponseCodes::SESSION_TOKEN_EXPIRED == e.code)
+          unless (attempts +=1) > 1
+            SparkApi.logger.debug("Retrying authentication")
+            authenticate
+            retry
+          end
+        end
+        # No luck authenticating... KABOOM!
+        SparkApi.logger.error("Authentication failed or server is sending us expired tokens, nothing we can do here.")
+        raise
+      end
+      response.body
+    end
+    
+  end
+ 
+end

data/lib/spark_api/request.rb~

@@ -0,0 +1,96 @@
+require 'cgi'
+
+module FlexmlsApi
+  # HTTP request wrapper.  Performs all the api session mumbo jumbo so that the models don't have to.
+  module Request
+    # Perform an HTTP GET request
+    # 
+    # * path - Path of an api resource, excluding version and endpoint (domain) information
+    # * options - Resource request options as specified being supported via and api resource
+    # :returns:
+    #   Hash of the json results as documented in the api.
+    # :raises:
+    #   FlexmlsApi::ClientError or subclass if the request failed.
+    def get(path, options={})
+      request(:get, path, nil, options)
+    end
+
+    # Perform an HTTP POST request
+    # 
+    # * path - Path of an api resource, excluding version and endpoint (domain) information
+    # * body - Hash for post body data
+    # * options - Resource request options as specified being supported via and api resource
+    # :returns:
+    #   Hash of the json results as documented in the api.
+    # :raises:
+    #   FlexmlsApi::ClientError or subclass if the request failed.
+    def post(path, body={}, options={})
+      request(:post, path, body, options)
+    end
+
+    # Perform an HTTP PUT request
+    # 
+    # * path - Path of an api resource, excluding version and endpoint (domain) information
+    # * body - Hash for post body data
+    # * options - Resource request options as specified being supported via and api resource
+    # :returns:
+    #   Hash of the json results as documented in the api.
+    # :raises:
+    #   FlexmlsApi::ClientError or subclass if the request failed.
+    def put(path, body={}, options={})
+      request(:put, path, body, options)
+    end
+
+    # Perform an HTTP DELETE request
+    # 
+    # * path - Path of an api resource, excluding version and endpoint (domain) information
+    # * options - Resource request options as specified being supported via and api resource
+    # :returns:
+    #   Hash of the json results as documented in the api.
+    # :raises:
+    #   FlexmlsApi::ClientError or subclass if the request failed.
+    def delete(path, options={})
+      request(:delete, path, nil, options)
+    end
+    
+    private
+
+    # Perform an HTTP request (no data)
+    def request(method, path, body, options)
+      unless authenticated?
+        authenticate
+      end
+      attempts = 0
+      begin
+        request_opts = {}
+        request_opts.merge!(options)
+        post_data = body.nil? ? nil : {"D" => body }.to_json
+        request_path = "/#{version}#{path}"
+        start_time = Time.now
+        FlexmlsApi.logger.debug("#{method.to_s.upcase} Request:  #{request_path}")
+        if post_data.nil?
+          response = authenticator.request(method, request_path, nil, request_opts)
+        else
+          FlexmlsApi.logger.debug("#{method.to_s.upcase} Data:   #{post_data}")
+          response = authenticator.request(method, request_path, post_data, request_opts)
+        end
+        request_time = Time.now - start_time
+        FlexmlsApi.logger.info("[#{(request_time * 1000).to_i}ms] Api: #{method.to_s.upcase} #{request_path}")
+      rescue PermissionDenied => e
+        if(ResponseCodes::SESSION_TOKEN_EXPIRED == e.code)
+          unless (attempts +=1) > 1
+            FlexmlsApi.logger.debug("Retrying authentication")
+            authenticate
+            retry
+          end
+        end
+        # No luck authenticating... KABOOM!
+        FlexmlsApi.logger.error("Authentication failed or server is sending us expired tokens, nothing we can do here.")
+        raise
+      end
+      response.body
+    end
+    
+  end
+ 
+end