yieldmanager 0.1.1 → 0.2.0

data/README.rdoc

@@ -7,7 +7,7 @@ Currently it generates a fresh wsdl from the api.yieldmanager.com site the
 first time you use a service (in the future it will use locally-cached
 copies) and re-uses that wsdl for the life of the Yieldmanager::Client object.
 
-== Creating a Yieldmanager::Client
+=== Creating a Yieldmanager::Client
 
 	@ym = Yieldmanager::Client(
 		:user => "bob",
@@ -15,17 +15,35 @@ copies) and re-uses that wsdl for the life of the Yieldmanager::Client object.
 		:api_version => "1.30"
 	)
 
-== Finding available services
+=== Finding available services
 
 	@ym.available_services
 
-== Using a service
+=== Using a service
 
 	@ym.session do |token|
 		currencies = @ym.dictionary.getCurrencies(token)
 	end
+	
+=== Pagination
 
-== session vs. start_session/end_session
+Some calls return datasets too large to retrieve all at once.
+Pagination allows you to pull them back incrementally, handling
+the partial dataset on-the-fly or accumulating it for later use.
+
+	BLOCK_SIZE = 50
+	id = 1
+	@ym.session do |token|
+		@ym.paginate(BLOCK_SIZE) do |block|
+			(lines,tot) = line_item_service.getByBuyer(token,id,BLOCK_SIZE,block)
+			# ...do something with lines...
+			
+      # remember to return total!
+      tot
+		end
+	end
+
+=== session vs. start_session/end_session
 
 The +session+ method opens a session, gives you a token to use in your service
 calls, then closes the session when the block ends, even if an exception is

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.0

data/lib/yieldmanager/client.rb

@@ -79,6 +79,19 @@ module Yieldmanager
         end_session token
       end
     end
+    
+    # Allows looping over datasets too large to pull back in one call
+    #
+    # Block must return total rows in dataset to know when to stop!
+    def paginate block_size
+      page = 1
+      total = block_size + 1
+
+      begin
+        total = yield page # Need total back from block to know when to stop!
+        page += 1
+      end until (block_size * (page-1)) > total
+    end
 
 private
     

data/spec/yieldmanager/client_spec.rb

@@ -72,6 +72,31 @@ describe "A new Yieldmanager client" do
     lambda { @ym.dictionary.getCurrencies(my_token) }.should raise_error(SOAP::FaultError)
   end
   
+  it "paginates" do
+    BLOCK_SIZE = 50
+    id = -1
+    @ym.session do |token|
+      line_item_service = @ym.line_item
+      [
+        {:calls_expected => 2, :dataset_size => 75},
+        {:calls_expected => 1, :dataset_size => 25},
+        {:calls_expected => 1, :dataset_size => 0}
+      ].each do |args|
+        line_item_service.
+          should_receive(:getByBuyer).
+          exactly(args[:calls_expected]).times.
+          and_return([[],args[:dataset_size]])
+        @ym.paginate(BLOCK_SIZE) do |block|
+          (lines,tot) = line_item_service.
+            getByBuyer(token,id,BLOCK_SIZE,block)
+          # must return total rows in dataset
+          # so paginate knows when to stop!
+          tot
+        end
+      end
+    end
+  end
+  
   def login_args
     unless ENV["YIELDMANAGER_USER"] &&
       ENV["YIELDMANAGER_PASS"] &&

data/yieldmanager.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{yieldmanager}
-  s.version = "0.1.1"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Bill Gathen"]
-  s.date = %q{2009-11-17}
+  s.date = %q{2009-11-18}
   s.description = %q{This gem offers full access to YieldManager's API tools (read/write) as well as ad-hoc reporting through the Reportware tool}
   s.email = %q{bill@billgathen.com}
   s.extra_rdoc_files = [

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: yieldmanager
 version: !ruby/object:Gem::Version 
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors: 
 - Bill Gathen
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-17 00:00:00 -05:00
+date: 2009-11-18 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency