ruby_odata 0.0.3 → 0.0.4

data/CHANGELOG.rdoc

@@ -1,13 +1,22 @@
 = ruby_odata Change Log
 
 === 0.0.1 
-* Basic CRUD Operations
-* Query: Filters
-* Query: Expands
+* New Features
+  * Basic CRUD Operations
+  * Query Enhancement: Filters
+  * Query Enhancement: Expands
 
 === 0.0.2
-* Query: Order By
+* New Features
+  * Query Enhancement: Order By (both desc and asc)
 
 === 0.0.3
-* Rearranged code to match the gem name.  Things were mismatched between odata_ruby and ruby_odata.
+* Bug Fixes
+  * Rearranged code to match the gem name.  Things were mismatched between odata_ruby and ruby_odata.
 
+=== 0.0.4
+* New Features
+  * Query Enhancement: skip
+  * Query Enhancement: top
+  * Ability to perform paging using skip and top together
+  * Updated README with examples for order_by, skip, and top

data/README.rdoc

@@ -1,3 +1,4 @@
+Error: The word "DATABASE SETUP - DO THIS FIRST*" is invalid. The character ' ' (U+20) may not appear in the middle of a word.
 = ruby_odata
 
 The <b>Open Data Protocol</b> (OData) is a fantastic way to query and update data over standard Web technologies.  The ruby_odata library acts as a consumer of OData services.
@@ -60,9 +61,12 @@ Querying is easy, for example to pull all the categories from the SampleService,
 	categories = svc.execute
 	puts categories.to_json
 
-You can also expand and add filters to the query before executing it.  For example:
+You can also expand, add filters, order, skip records, and take only the top X records to the query before executing it.  For example:
 
 === Expanding
+Expanding allows you to eagerly load other objects that are children of the root.
+You can use more than one expand on a query.  
+For expanding grandchild and lower entities, you must pass in the full path from the root, for example +Products.expand('Orders').expand('Orders/LineItems')+
 
 	# Without expanding the query
 	svc.Products(1)
@@ -78,6 +82,8 @@ You can also expand and add filters to the query before executing it.  For examp
 
 
 === Filtering
+The syntax for filtering can be found on the {OData Protocol URI Conventions}[http://www.odata.org/developers/protocols/uri-conventions#FilterSystemQueryOption] page.
+You can use more than one filter, if you call the filter method multiple times it will before an AND.
 
 	# You can access by ID (but that isn't is a filter)
 	# The syntax is just svc.ENTITYNAME(ID) which is shown in the expanding examples above
@@ -88,17 +94,44 @@ You can also expand and add filters to the query before executing it.  For examp
 	puts "#{prod.to_json}"
 	
 === Combining Expanding and Filtering
+The query operations follow a {fluent interface}[http://en.wikipedia.org/wiki/Fluent_interface], although they can be added by themselves as well as chained
 
 	svc.Products.filter("Name eq 'Product 2'").expand("Category")
 	prod = svc.execute
 	puts "Filtering on Name eq 'Product 2' and expanding"
 	puts "#{prod.to_json}"
 
+=== Order By
+You can order the results by properties of your choice, either ascending or descending.
+Order by are similar to +expand+s in that you can use more than one of them on a query.
+For expanding grandchild and lower entities, you must pass in the full path from the root like would do on an +expand+
 
+	svc.Products.order_by("Name")
+	products = svc.execute
+
+	# Specifically requesting descending
+	svc.Products.order_by("Name desc")
+	products = svc.execute
+	
+	# Specifically requesting ascending
+	svc.Products.order_by("Name asc")
+	products = svc.execute
+	
+=== Skip
+Skip allows you to skip a number of records when querying.  This is often used for paging along with +top+.
+	
+	svc.Products.skip(5)
+	products = svc.execute # => skips the first 5 items 
+	
+=== Top
+Top allows you only retrieve the top X number of records when querying.  This is often used for paging along with +skip+.
+	
+	svc.Products.top(5)
+	products = svc.execute # => returns only the first 5 items	
 
 == Tests
 *DATABASE SETUP - DO THIS FIRST*
-Within /test/SampleService/App_Data/ rename _TestDB*.* to TestDB*.*. This file is just the inital database, and needs to be renamed so that unwanted changes to that DB aren't persisted in source control.
+Within /test/SampleService/App_Data/ rename _TestDB*.* to TestDB*.*. This file is just the initial database, and needs to be renamed so that unwanted changes to that DB aren't persisted in source control.
 
 All of the tests are written using Cucumber going against a sample service (Found in /test/SampleService/*).  The SampleService is an ASP.NET Web Site running a SQLEXPRESS 2008 R2 Database (TestDB), as well as the ADO.NET Entity Framework and a WCF Data Service.  In order to run the tests, you need to spin up the SampleService and have it running on port 8888 (http://localhost:8888/SampleService).  
 

data/VERSION

@@ -1 +1 @@
-0.0.3
+0.0.4

data/features/query_builder.feature

@@ -21,8 +21,9 @@ Scenario: Navigation Properties should be able to be eager loaded
 	And the method "Id" on the result's method "Category" should equal: "1"
 
 
-# Filter
+# Filters
 Scenario: Filters should be allowed on the root level entity
+# Filter
   Given I call "AddToProducts" on the service with a new "Product" object with Name: "Test Product"
   When I save changes
   When I call "Products" on the service
@@ -90,6 +91,62 @@ Scenario: Order by should access sorting acsending
   | Product 5 |
 
 
+# Skip
+Scenario: Skip should be allowed on the root level entity
+  Given the following Products exist:
+  | Name      |
+  | Product 1 |
+  | Product 2 |
+  | Product 3 |
+  | Product 4 |
+  | Product 5 | 
+  When I call "Products" on the service
+  And I skip 3
+  And I run the query
+  Then the result should be:
+  | Name      |
+  | Product 4 |
+  | Product 5 |  
+
+
+# Top
+Scenario: Top should be allowed on the root level entity
+  Given the following Products exist:
+  | Name      |
+  | Product 1 |
+  | Product 2 |
+  | Product 3 |
+  | Product 4 |
+  | Product 5 | 
+  When I call "Products" on the service
+  And I ask for the top 3
+  And I run the query
+  Then the result should be:
+  | Name      |
+  | Product 1 |
+  | Product 2 | 
+  | Product 3 |
+
+Scenario: Top should be able to be used along with skip for paging
+  Given the following Products exist:
+  | Name      |
+  | Product 1 |
+  | Product 2 |
+  | Product 3 |
+  | Product 4 |
+  | Product 5 | 
+  | Product 6 |  
+  When I call "Products" on the service
+  And I skip 2
+  And I ask for the top 2
+  And I run the query
+  Then the result should be:
+  | Name      |
+  | Product 3 |
+  | Product 4 |  
+
+
+
 
   
 

data/features/step_definitions/service_steps.rb

@@ -62,6 +62,13 @@ When /^I order by: "([^\"]*)"$/ do |order|
   @service_query.order_by(order)
 end
 
+When /^I skip (\d+)$/ do |skip|
+  @service_query.skip(skip)
+end
+
+When /^I ask for the top (\d+)$/ do |top|
+	@service_query.top(top)
+end
 
 Then /^the method "([^\"]*)" on the result should be of type "([^\"]*)"$/ do |method, type|
   result = @service_result.send(method.to_sym) 

data/lib/ruby_odata/query_builder.rb

@@ -15,6 +15,8 @@ class QueryBuilder
 		@expands = []
 		@filters = []
 		@order_bys = []
+		@skip = nil
+		@top = nil
 	end
 	
 	# Used to eagerly-load data for nested objects, for example, obtaining a Category for a Product within one call to the server
@@ -36,7 +38,7 @@ class QueryBuilder
 	
 	# Used to filter data being returned
 	# ==== Required Attributes
-	# - filter: The path of the entity to expand relative to the root
+	# - filter: The conditions to apply to the query
 	#
 	# ==== Example	
 	# 	svc.Products.filter("Name eq 'Product 2'")
@@ -58,6 +60,32 @@ class QueryBuilder
 		self
 	end
 	
+	# Used to skip a number of records 
+	# This is typically used for paging, where it would be used along with the +top+ method.
+	# ==== Required Attributes
+	# - num: The number of items to skip
+	#
+	# ==== Example	
+	# 	svc.Products.skip(5)
+	# 	products = svc.execute # => skips the first 5 items	
+	def skip(num)
+		@skip = num
+		self
+	end
+	
+	# Used to take only the top X records 
+	# This is typically used for paging, where it would be used along with the +skip+ method.
+	# ==== Required Attributes
+	# - num: The number of items to return
+	#
+	# ==== Example	
+	# 	svc.Products.top(5)
+	# 	products = svc.execute # => returns only the first 5 items	
+	def top(num)
+		@top = num
+		self
+	end
+	
 	# Builds the query URI (path, not including root) incorporating expands, filters, etc.
 	# This is used internally when the execute method is called on the service
 	def query
@@ -66,6 +94,8 @@ class QueryBuilder
 		query_options << "$expand=#{@expands.join(',')}" unless @expands.empty?
 		query_options << "$filter=#{@filters.join('+and+')}" unless @filters.empty?
 		query_options << "$orderby=#{@order_bys.join(',')}" unless @order_bys.empty?
+		query_options << "$skip=#{@skip}" unless @skip.nil?
+		query_options << "$top=#{@top}" unless @top.nil?
 		if !query_options.empty?
 			q << "?"
 			q << query_options.join('&')	

data/ruby_odata.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{ruby_odata}
-  s.version = "0.0.3"
+  s.version = "0.0.4"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Damien White"]

data/test/blueprints.rb

@@ -1,7 +1,7 @@
 Sham.define do
-  category_name  	{ |i| "Category #{i}" }
-  product_name 		{ |i| "Widget #{i}" }
-  price						{ ['5.00', '10.00', '20.00', '15.00' , '25.00', '7.50'].rand }
+  category_name  					{ |i| "Category #{i}" }
+  product_name 						{ |i| "Widget #{i}" }
+  price(:unique => false)	{ ['5.00', '10.00', '20.00', '15.00' , '25.00', '7.50'].rand }
 end
 
 Product.blueprint do

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: ruby_odata
 version: !ruby/object:Gem::Version 
-  hash: 25
+  hash: 23
   prerelease: false
   segments: 
   - 0
   - 0
-  - 3
-  version: 0.0.3
+  - 4
+  version: 0.0.4
 platform: ruby
 authors: 
 - Damien White