restforce 1.2.0 → 1.3.0

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 1.3.0 (Apr 6, 2013)
+
+*   Added support for lazily traversing paginated collections #61 by @nahiluhmot.
+
+## 1.2.0 (Mar 30, 2013)
+
+*   Added support for proxies #60 by @wazoo.
+
 ## 1.1.0 (Mar 3, 2013)
 
 *   Added ability to download attachments easily.

data/README.md

@@ -395,7 +395,7 @@ end
 
 * * *
 
-### Logging/Debugging
+### Logging/Debugging/Instrumenting
 
 You can easily inspect what Restforce is sending/receiving by setting
 `Restforce.log = true`.
@@ -407,16 +407,19 @@ client = Restforce.new.query('select Id, Name from Account')
 
 Another awesome feature about restforce is that, because it is based on
 Faraday, you can insert your own middleware. For example, if you were using
-Restforce in a rails app, you can setup custom logging using
-ActiveSupport::Notifications:
+Restforce in a rails app, you can setup custom reporting to
+[Librato](https://github.com/librato/librato-rails) using ActiveSupport::Notifications:
 
 ```ruby
 client = Restforce.new
-client.middleware.insert_after Restforce::Middleware::InstanceURL, FaradayMiddleware::Instrumentation
+client.middleware.insert_after Restforce::Middleware::InstanceURL,
+  FaradayMiddleware::Instrumentation, name: 'request.salesforce'
 
 # config/initializers/notifications.rb
-ActiveSupport::Notifications.subscribe('request.faraday') do |name, start, finish, id, payload|  
-  Rails.logger.debug(['notification:', name, "#{(finish - start) * 1000}ms", payload[:status]].join(" "))  
+ActiveSupport::Notifications.subscribe('request.salesforce') do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  Librato.increment 'api.salesforce.request.total'
+  Librato.timing 'api.salesforce.request.time', event.duration
 end
 ```
 

data/lib/restforce/client.rb

@@ -16,10 +16,6 @@ module Restforce
     include Restforce::Client::Canvas
     include Restforce::Client::API
 
-    OPTIONS = [:username, :password, :security_token, :client_id, :client_secret, :host, :compress,
-       :api_version, :oauth_token, :refresh_token, :instance_url, :cache, :authentication_retries,
-       :timeout, :proxy_uri]
-
     # Public: Creates a new client instance
     #
     # opts - A hash of options to be passed in (default: {}).
@@ -76,7 +72,7 @@ module Restforce
     #
     def initialize(opts = {})
       raise 'Please specify a hash of options' unless opts.is_a?(Hash)
-      @options = Hash[OPTIONS.map { |option| [option, Restforce.configuration.send(option)] }]
+      @options = Hash[Restforce.configuration.options.map { |option| [option, Restforce.configuration.send(option)] }]
       @options.merge! opts
     end
 

data/lib/restforce/collection.rb

@@ -1,18 +1,40 @@
 module Restforce
-  class Collection < Array
-    attr_reader :total_size, :next_page_url
+  class Collection
+    include Enumerable
 
+    # Given a hash and client, will create an Enumerator that will lazily
+    # request Salesforce for the next page of results.
     def initialize(hash, client)
-      @client        = client
-      @total_size    = hash['totalSize']
-      @next_page_url = hash['nextRecordsUrl']
-      super(Restforce::Mash.build(hash['records'], @client))
+      @client = client
+      @raw_page = hash
     end
 
-    def next_page
-      response = @client.get next_page_url
-      response.body
+    # Yield each value on each page.
+    def each
+      @raw_page['records'].each { |record| yield Restforce::Mash.build(record, @client) }
+
+      next_page.each { |record| yield record } if has_next_page?
+    end
+
+    # Return the size of the Collection without making any additional requests.
+    def size
+      @raw_page['totalSize']
+    end
+    alias_method :length, :size
+
+    # Return the current and all of the following pages.
+    def pages
+      [self] + (has_next_page? ? next_page.pages : [])
+    end
+
+    # Returns true if there is a pointer to the next page.
+    def has_next_page?
+      !@raw_page['nextRecordsUrl'].nil?
     end
 
+    # Returns the next page as a Restforce::Collection if it's available, nil otherwise.
+    def next_page
+      @next_page ||= @client.get(@raw_page['nextRecordsUrl']).body if has_next_page?
+    end
   end
 end

data/lib/restforce/config.rb

@@ -37,85 +37,70 @@ module Restforce
   end
 
   class Configuration
-    attr_accessor :api_version
+    class << self
+      attr_accessor :options
+
+      def option(name, options = {})
+        default = options.fetch(:default, nil)
+        attr_accessor name
+        define_method name do
+          instance_variable_get(:"@#{name}") ||
+            instance_variable_set(:"@#{name}", default.respond_to?(:call) ? default.call : default)
+        end if default
+        self.options ||= []
+        self.options << name
+      end
+    end
+
+    option :api_version, :default => '26.0'
+
     # The username to use during login.
-    attr_accessor :username
+    option :username, :default => lambda { ENV['SALESFORCE_USERNAME'] }
+
     # The password to use during login.
-    attr_accessor :password
+    option :password, :default => lambda { ENV['SALESFORCE_PASSWORD'] }
+
     # The security token to use during login.
-    attr_accessor :security_token
+    option :security_token, :default => lambda { ENV['SALESFORCE_SECURITY_TOKEN'] }
+
     # The OAuth client id
-    attr_accessor :client_id
+    option :client_id, :default => lambda { ENV['SALESFORCE_CLIENT_ID'] }
+
     # The OAuth client secret
-    attr_accessor :client_secret
+    option :client_secret, :default => lambda { ENV['SALESFORCE_CLIENT_SECRET'] }
+
     # Set this to true if you're authenticating with a Sandbox instance.
     # Defaults to false.
-    attr_accessor :host
+    option :host, :default => 'login.salesforce.com'
 
-    attr_accessor :oauth_token
-    attr_accessor :refresh_token
-    attr_accessor :instance_url
+    option :oauth_token
+    option :refresh_token
+    option :instance_url
 
     # Set this to an object that responds to read, write and fetch and all GET
     # requests will be cached.
-    attr_accessor :cache
+    option :cache
 
     # The number of times reauthentication should be tried before failing.
-    attr_accessor :authentication_retries
+    option :authentication_retries, :default => 3
 
     # Set to true if you want responses from Salesforce to be gzip compressed.
-    attr_accessor :compress
+    option :compress
 
     # Faraday request read/open timeout.
-    attr_accessor :timeout
+    option :timeout
 
     # Faraday adapter to use. Defaults to Faraday.default_adapter.
-    attr_accessor :adapter
-
-    attr_accessor :proxy_uri
-
-    def api_version
-      @api_version ||= '26.0'
-    end
-
-    def username
-      @username ||= ENV['SALESFORCE_USERNAME']
-    end
-
-    def password
-      @password ||= ENV['SALESFORCE_PASSWORD']
-    end
+    option :adapter, :default => lambda { Faraday.default_adapter }
 
-    def security_token
-      @security_token ||= ENV['SALESFORCE_SECURITY_TOKEN']
-    end
-
-    def client_id
-      @client_id ||= ENV['SALESFORCE_CLIENT_ID']
-    end
-
-    def client_secret
-      @client_secret ||= ENV['SALESFORCE_CLIENT_SECRET']
-    end
-
-    def proxy_uri
-      @proxy_uri ||= ENV['PROXY_URI']
-    end
-
-    def host
-      @host ||= 'login.salesforce.com'
-    end
-
-    def authentication_retries
-      @authentication_retries ||= 3
-    end
-
-    def adapter
-      @adapter ||= Faraday.default_adapter
-    end
+    option :proxy_uri, :default => lambda { ENV['PROXY_URI'] }
 
     def logger
       @logger ||= ::Logger.new STDOUT
     end
+
+    def options
+      self.class.options
+    end
   end
 end

data/lib/restforce/version.rb

@@ -1,3 +1,3 @@
 module Restforce
-  VERSION = '1.2.0'
+  VERSION = '1.3.0'
 end

data/spec/lib/client_spec.rb

@@ -97,7 +97,7 @@ shared_examples_for 'methods' do
     requests 'query\?q=SELECT%20some,%20fields%20FROM%20object', :fixture => 'sobject/query_success_response'
 
     subject { client.query('SELECT some, fields FROM object') }
-    it { should be_an Array }
+    it { should be_an Enumerable }
   end
 
   describe '.search' do
@@ -364,7 +364,7 @@ shared_examples_for 'methods' do
 
     let(:cache) { MockCache.new }
     subject { client.without_caching { client.query('SELECT some, fields FROM object') } }
-    it { should be_an Array }
+    it { should be_an Enumerable }
   end
 
   unless RUBY_PLATFORM == 'java'
@@ -453,7 +453,7 @@ shared_examples_for 'methods' do
     end
 
     subject { client.query('SELECT some, fields FROM object') }
-    it { should be_an Array }
+    it { should be_an Enumerable }
   end
 end
 

data/spec/lib/collection_spec.rb

@@ -11,10 +11,9 @@ describe Restforce::Collection do
         described_class.new(JSON.parse(fixture('sobject/query_success_response')), client)
       end
 
-      it               { should respond_to :each }
-      its(:size)       { should eq 1 }
-      its(:total_size) { should eq 1 }
-      its(:next_page_url)  { should be_nil }
+      it                   { should respond_to :each }
+      its(:size)           { should eq 1 }
+      its(:has_next_page?) { should be_false }
       specify { expect(subject.instance_variable_get(:@client)).to eq client }
 
       describe 'each record' do
@@ -24,23 +23,29 @@ describe Restforce::Collection do
     end
 
     context 'with pagination' do
-      let(:records) do
-        described_class.new(JSON.parse(fixture('sobject/query_paginated_first_page_response')), client)
-      end
+      let(:first_page) { JSON.parse(fixture('sobject/query_paginated_first_page_response')) }
+      let(:next_page) { JSON.parse(fixture('sobject/query_paginated_last_page_response')) }
+      let(:records) { described_class.new(first_page, client) }
 
-      it               { should respond_to :each }
-      its(:size)       { should eq 1 }
-      its(:total_size) { should eq 2 }
-      its(:next_page_url)  { should eq "/services/data/v#{Restforce.configuration.api_version}/query/01gD" }
+      it { should respond_to :each }
       specify { expect(subject.instance_variable_get(:@client)).to eq client }
 
-      describe '.next_page' do
+      context 'when only values from the first page are being requested' do
+        before { client.should_not_receive(:get) }
+
+        its(:size) { should eq 2 }
+        its(:first) { should be_an_instance_of Restforce::SObject }
+      end
+
+      context 'when all of the values are being requested' do
         before do
-          client.should_receive(:get).and_return(Faraday::Response.new(:body => Restforce::Collection.new({'records' => []}, client)))
+          client.stub(:get).and_return(Faraday::Response.new(:body => Restforce::Collection.new(next_page, client)))
         end
 
-        subject { records.next_page }
-        it { should be_a Restforce::Collection }
+        its(:pages)          { should be_all { |page| expect(page).to be_a Restforce::Collection } }
+        its(:has_next_page?) { should be_true }
+        it { should be_all { |record| expect(record).to be_a Restforce::SObject } }
+        specify { subject.next_page.should be_a Restforce::Collection }
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: restforce
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-30 00:00:00.000000000 Z
+date: 2013-04-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -252,7 +252,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1651043006991876016
+      hash: 2514062890750763667
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -261,7 +261,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1651043006991876016
+      hash: 2514062890750763667
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23