ruby_odata 0.1.0 → 0.1.6

data/CHANGELOG.rdoc

@@ -1,88 +0,0 @@
-= ruby_odata Change Log
-
-=== 0.0.1 
-* New Features
-  * Basic CRUD Operations
-  * Query Enhancement: Filters
-  * Query Enhancement: Expands
-
-=== 0.0.2
-* New Features
-  * Query Enhancement: Order By (both desc and asc)
-
-=== 0.0.3
-* 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
-  
-=== 0.0.5
-* Bug Fixes
-  * Works with Ruby 1.9.1
-  * Works with ActiveSupport 3.0.0.beta4
-  
-=== 0.0.6
-* New Features
-  * Ability to batch saves (Adds, Updates, Deletes); this will help save on network chatter
-
-=== 0.0.7
-* New Features
-  * Complex Types are now supported
-  * Support for Edm.Int16, Edm.Int32, Edm.Int64
-  * Support for Edm.Decimal
-  * Support for Edm.DateTime
-  
-=== 0.0.8
-* New Features
-  * Basic HTTP Authentication (thanks J.D. Mullin)
-  * Modified cucumber tests to setup the test database so you no longer need to copy them yourself
-  * Support for nullable elements returned from the Data Service (m:null ="true")
-* Bug Fixes
-  * ActiveSupport 2.3.x (tested 2.3.11) and 3.0.x (tested 3.0.4) are now supported
-  * Works with Ruby 1.9.2
-
-=== 0.0.9
-* New Features
-  * Support for self-signed SSL certificates (thanks J.D. Mullin)
-  * Refactored building classes/collections to only make one call to the service
-  * Added support for a WCF service with lowercase entities (reported by Klaus Rohe)
-* Bug Fixes
-  * Fixed issue with passing a service URL with a trailing slash
-* Other
-  * Cleaned up testing by adding a default task to the Rakefile that runs RSpec and Cucumber
-
-=== 0.0.10
-* New Features
-  * Added the ability to pass additional parameters that are appended to the query string for requests
-  * Added initial support for feed customizations (SyndicationTitle and SyndicationSummary)
-  * Enhanced ruby_odata's awareness of classes based on the metadata instead of relying on results that are returned
-* Bug Fixes
-  * Fixed issues with nested collections (eager loading)
-  * Handled ArgumentError on the Time.parse for older versions of Ruby; used DateTime.parse instead if Time.parse fails
-  * Removed the camelize method call when building the root URL for collections (Reported by mkoegel, issue #3 on github)
-  * Handled building results (classes) where the category element is missing but there is a title element instead. (Reported by mkoegel, issue #3 on github in the comments)
-* Other
-  * Change HTTP port to 8989 since 8888 conflicts with the Intel AppStore
-  * Refactored service step for HTTP calls where the service address is defined within the step making it easier to make changes in the future.
-
-=== 0.1.0
-* **BREAKING CHANGES**
-  * Previously the ruby_odata +Service.execute+ and +Service.save_changes+ used to return a single entity object if there was only one result returned. Now, the results are always an Enumerable (except in the case of boolean results like a delete), so if you just need one result, use the +first+ method on the result set
-* New Features
-  * Support for partial results (thanks arienmalec)
-  * Added support for single layer inheritance (thanks to http://odetocode.com/Blogs/scott/archive/2010/07/11/odata-and-ruby.aspx)
-  * Added support for querying links (see https://github.com/visoft/ruby_odata/issues/10)
-  * Added support for adding links between entities (add_link)
-  * Added support for lazy loading
-  * Added a convenience method (+first+) for accessing a single result by id
-  * Added basic reflection of the entity model via the ruby_odata service
-  * Added the ability to create ruby_odata models in a specified namespace to prevent conflicts with local models
-  * Added the ability to call function imports exposed by the WCF Data Service
-* Other
-  * Changed the test project (for Cucumber integration tests) to use SQL Compact 4, Entity Framework 4.1, and WCF Data Services October 2011 CTP
-  * Added {Pickle}[https://github.com/ianwhite/pickle] integration to simplify Cucumber step definitions

data/README.rdoc

@@ -1,259 +0,0 @@
-= 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.
-
-== Resources
-
-* Source Code (hosted on GitHub): http://github.com/visoft/ruby_odata 
-* Documentation (hosted on rdoc.info): http://rdoc.info/projects/visoft/ruby_odata 
-* Issue tracking (hosted on GitHub): https://github.com/visoft/ruby_odata/issues
-* Wiki (hosted on GitHub): http://wiki.github.com/visoft/ruby_odata/
-* Gem (hosted on Gemcutter): http://gemcutter.org/gems/ruby_odata
-* Blog articles: 
-  * {Introducing a Ruby OData Client Library}[http://bit.ly/IntroRubyOData]
-  * {Ruby OData Update v0.0.7}[http://bit.ly/ruby_odata007]
-  * {Ruby OData Update v0.0.8}[http://bit.ly/ruby_odata008]
-  * {Ruby OData Update v0.0.10}[http://bit.ly/ruby_odata0010]
-
-== Installation
-You can install ruby_odata as a gem using:
-  gem install ruby_odata
-
-== Usage
-
-=== Instantiating the Service
-There are various options that you can pass when creating an instance of the service, these include:
-* username: username for http basic auth
-* password: password for http basic auth
-* verify_ssl: false if no verification, otherwise mode (OpenSSL::SSL::VERIFY_PEER is default)
-* additional_params: a hash of query string params that will be passed on all calls (query, new, update, delete, batch)
-* namespace: a string based namespace to create your objects in. You can specify the namespace using periods as separators (like .NET, for example <tt>VisoftInc.Sample.Models</tt>) or using double colons as separators (like Ruby <tt>VisoftInc::Sample::Models</tt>). By providing a namespace you can prevent naming collisions in your applications. 
-
-=== Adding
-When you point at a service, an AddTo<EntityName> method is created for you.  This method takes in the new entity to create.  To commit the change, you need to call the save_changes method on the service.  To add a new category for example, you would simply do the following:
-
-  require 'ruby_odata'
-  
-  svc = OData::Service.new "http://127.0.0.1:8989/SampleService/RubyOData.svc"
-  new_category = Category.new
-  new_category.Name = "Sample Category"
-  svc.AddToCategories(new_category)
-  category = svc.save_changes
-  puts category.to_json
-
-=== Updating
-To update an object, simply pass the modified object to the update_object method on the service. Updating, like adding requires you to call save_changes in order to persist the change.  For example:
-
-  require 'ruby_odata'
-    
-  svc = OData::Service.new "http://127.0.0.1:8989/SampleService/RubyOData.svc"
-  new_category = Category.new
-  new_category.Name = "Sample Category"
-  svc.AddToCategories(new_category)
-  category = svc.save_changes
-  puts category.to_json
-  
-  category.Name = 'Updated Category'
-  svc.update_object(category)
-  result = svc.save_changes
-  puts "Was the category updated? #{result}"
-  
-=== Deleting
-Deleting an object involves passing the tracked object to the delete_object method on the service.  Deleting is another function that involves the save_changes method (to commit the change back to the server).  In this example, we'll add a category and then delete it.
-
-  require 'ruby_odata'
-  
-  svc = OData::Service.new "http://127.0.0.1:8989/SampleService/RubyOData.svc"
-  new_category = Category.new
-  new_category.Name = "Sample Category"
-  svc.AddToCategories(new_category)
-  category = svc.save_changes
-  puts category.to_json
-  
-  svc.delete_object(category)
-  result = svc.save_changes
-  puts "Was the category deleted? #{result}"
-
-=== Add Link
-Adding a linkage between entities can now be performed outside of creation or modification of the objects. See the {OData documents}[http://www.odata.org/developers/protocols/operations#CreatingLinksbetweenEntries] for more details.
-To add a link between entities, simply call the +add_link+ method on the Service passing the parent object, the name of the navigation property, and the child object. Like all save operations, you need to call +save_changes+ to persist the changes.
-
-  svc.add_link(<Parent>, <Navigation Property Name>, <Child>)
-  svc.save_changes
-
-=== Querying
-Querying is easy, for example to pull all the categories from the SampleService, you simply can run:
-
-  require 'ruby_odata'
-  
-  svc = OData::Service.new "http://127.0.0.1:8989/SampleService/RubyOData.svc"
-  svc.Categories
-  categories = svc.execute
-  puts categories.to_json
-
-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 <tt>Products.expand('Orders').expand('Orders/LineItems')</tt>
-
-  # Without expanding the query
-  svc.Products(1)
-  prod1 = svc.execute
-  puts "Without expanding the query"
-  puts "#{prod1.to_json}\n"
-  
-  # With expanding the query
-  svc.Products(1).expand('Category')
-  prod1 = svc.execute
-  puts "With expanding the query"
-  puts "#{prod1.to_json}\n"
-
-=== Lazy Loading
-If you want to implement lazy loading, the ruby_odata `Service` allows you to perform this. You simply need to call the `load_property` method on the `Service` passing in the object and the navigation property to fill.
-
-  # Without expanding the query
-  svc.Products(1)
-  prod1 = svc.execute.first
-  puts "#{prod1.to_json}\n"
-
-  # Use load_property for lazy loading
-  svc.load_property(prod1, "Category")
-  puts "#{prod1.to_json}\n"
-
-=== 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
-  
-  svc.Products.filter("Name eq 'Product 2'")
-  prod = svc.execute
-  puts "Filtering on Name eq 'Product 2'"
-  puts "#{prod.to_json}"
-  
-Note you can pass more than one filter in the string, for example (querying Netflix): 
-
-  svc.Titles.filter("Rating eq 'PG' and ReleaseYear eq 1980")
-
-Filters can also be chained, by doing this you will create an "and" filter (just like the last example) when it is passed to the server.
-
-  svc.Titles.filter("Rating eq 'PG'").filter("ReleaseYear eq 1980")
-
-  
-=== 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 +expands+ 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
-  
-Like the fiter method, order_by statements can also be chained like so:
-
-  svc.Products.order_by("Name asc").order_by("Price desc")
-
-
-=== 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	
-
-=== Navigation Property Links Only Query
-OData allows you to {query navigation properties and only return the links for the entities}[http://www.odata.org/developers/protocols/uri-conventions#AddressingLinksBetweenEntries] (instead of the data)
-  svc.Categories(1).links("Products")
-  product_links = svc.execute # => returns URIs for the products under the Category with an ID of 1
-
-=== Partial feeds
-OData allows services to do server-side paging in Atom by defining a next link. The default behavior is to repeatedly consume partial feeds until the result set is complete.
-
-  svc.Partials
-  results = svc.execute # => retrieves all results in the Partials collection
-
-If desired (e.g., because the result set is too large to fit in memory), explicit traversal of partial results can be requested via options:
-
-  svc = OData::Service.new "http://example.com/Example.svc", { :eager_partial => false }
-  svc.Partials
-  results = svc.execute # => retrieves the first set of results returned by the server
-  if svc.partial? # => true if the last result set was a partial result set (i.e., had a next link)
-    results.concat svc.next # => retrieves the next set of results
-  end
-  while svc.partial? # => to retrieve all partial result sets
-    results.concat svc.next
-  end
-
-=== Authentication
-Basic HTTP Authentication is supported via sending a username and password as service constructor arguments:
-
-  require 'ruby_odata'
-  
-  svc = OData::Service.new "http://127.0.0.1:8989/SampleService/RubyOData.svc", { :username => "bob", :password=> "12345" }
-
-=== SSL/https Certificate Verification
-The certificate verification mode can be passed in the options hash via the :verify_ssl key. For example, to ignore verification in order to use a self-signed certificate:
-
-  require 'ruby_odata'
-
-  svc = OData::Service.new "https://127.0.0.1:44300/SampleService/RubyOData.svc", { :verify_ssl => false }
-
-Or an OpenSSL integer constant can be passed as well:
-
-  require 'ruby_odata'
-
-  svc = OData::Service.new "https://127.0.0.1:44300/SampleService/RubyOData.svc", { :verify_ssl => OpenSSL::SSL::VERIFY_PEER }
-                                                                                                         
-Default verification is OpenSSL::SSL::VERIFY_PEER. Note due to the way Ruby's Request object implements certificate checking, you CAN NOT pass OpenSSL::SSL::VERIFY_NONE, you must instead pass a boolean false.
-
-== Function Imports / Custom Service Methods
-Function Imports are custom service methods exposed by the WCF Data Service. Each function import will be created as a method on the ruby_odata Service. When you make a call to one of these, they return a result immediately without the need to call +execute+ or +save_changes+.
-
-== Reflection
-Instead of relying on looking at the EDMX directly, ruby_odata allows you to perform basic reflection on objects
-=== Service Level Methods
-* *Collections* - You can look at the collections exposed by a service by accessing the +collections+ method, which is a hash. The key is the name of the collection and the value is the hash with +edmx_type+, which returns the name of the type from the EDMX and <tt>:type</tt>, which is the local type that is created for you
-* *Classes* - To see the generated classes, you can utilize the +classes+ method on the service. The return result is a hash where the key is the class name and the value is the class type.
-* <b>Function Imports</b> - You can find any function import (custom service methods) exposed by the service by accessing the +function_imports+ method. This is a hash where the key is the Function Import name and the value is metadata about the Function Import.
-
-=== Class Level Methods
-* *Properties* - You can call the class method +properties+ on a generated class to see the method (properties) that were created. The returned result is a hash where the key is the property name and the value is metadata for the property like if it is nullable, the EDM Type, etc.
-
-== Tests
-All of the tests are written using Cucumber going against a sample service (Found in test/RubyODataService/RubyODataService/*).
-The SampleService is an ASP.NET Web Site running a SQL Compact 4 Database, which gets generated at runtime, as well as the ADO.NET Entity Framework 4.1 and WCF Data Services October 2011 CTP. The reason for the CTP is that WCF Data Services currently shipping with .NET 4 doesn't support Entity Framework 4.1's "Code First" approach (e.g. no EDMX, all POCOs)
-In order to run the tests, you need to spin up IIS running a virtual directory of SampleService on port 8989 (http://localhost:8989/SampleService) and another instance running on port 44300.
-
-*NOTE* The ports (8989 and 44300) and webserver (localhost by default) here are customizable thanks to <tt>/features/contants.rb</tt>. Take a look in there for the corresponding environment variables that you can set.
-
-The SampleService requires IIS or IIS Express. IIS Express is a free download from Microsoft and the preferred approach to running the application. Once installed, there is a batch file found in /test called "iisExpress x64.bat" that will spin up the appropriate instances needed for the Cucumber tests. There is a also an "iisExpress x86.bat" file for those of you running a 32-bit machine.  The only difference is the path to the Program Files directory.  Once you run the batch file, the web server will spin up.  To stop the server, use 'Q' and then enter or close the command window.
-
-If you are testing on a Windows machine, you may encounter a problem with using Cucumber and Ruby 1.9.2.  You will get a message when you fire up cucumber about missing msvcrt-ruby18.dll.  The fix for this is to make sure you have the {RubyInstaller DevKit}[https://github.com/oneclick/rubyinstaller/wiki/Development-Kit] installed, then do the following:
-  gem uninstall json
-  gem install json --platform=ruby -v 1.4.6
-
-Once the SampleService is running, from the BASE ruby_odata directory, simply type +rake+, which will run the RSpec and Cucumber specs. You can also run them separately <tt>rake spec</tt> for RSpec and <tt>rake features</tt> for Cucumber.
-