ruby_odata 0.1.0 → 0.1.1

data/lib/ruby_odata/service.rb

@@ -1,17 +1,16 @@
 module OData
-  
+# The main service class, also known as a *Context*
 class Service
   attr_reader :classes, :class_metadata, :options, :collections, :edmx, :function_imports
   # Creates a new instance of the Service class
   #
-  # ==== Required Attributes
-  # - service_uri: The root URI of the OData service
-  # ==== Options in options hash
-  # - 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
-  # - eager_partial: true (default) if queries should consume partial feeds until the feed is complete, false if explicit calls to next must be performed
+  # @param [String] service_uri the root URI of the OData service
+  # @param [Hash] options the options to pass to the service
+  # @option options [String] :username for http basic auth
+  # @option options [String] :password for http basic auth
+  # @option options [Object] :verify_ssl false if no verification, otherwise mode (OpenSSL::SSL::VERIFY_PEER is default)
+  # @option options [Hash] :additional_params a hash of query string params that will be passed on all calls
+  # @option options [Boolean, true] :eager_partial true if queries should consume partial feeds until the feed is complete, false if explicit calls to next must be performed
   def initialize(service_uri, options = {})
     @uri = service_uri.gsub!(/\/?$/, '')
     set_options! options
@@ -20,7 +19,7 @@ class Service
     build_collections_and_classes
   end
 
-  # Handles the dynamic AddTo<EntityName> methods as well as the collections on the service
+  # Handles the dynamic `AddTo<EntityName>` methods as well as the collections on the service
   def method_missing(name, *args)
     # Queries
     if @collections.include?(name.to_s)
@@ -45,31 +44,29 @@ class Service
 
   # Queues an object for deletion.  To actually remove it from the server, you must call save_changes as well.
   #
-  # ==== Required Attributes
-  # - obj: The object to mark for deletion
+  # @param [Object] obj the object to mark for deletion
   #
-  # Note: This method will throw an exception if the +obj+ isn't a tracked entity
+  # @raise [NotSupportedError] if the `obj` isn't a tracked entity
   def delete_object(obj)
     type = obj.class.to_s
     if obj.respond_to?(:__metadata) && !obj.send(:__metadata).nil?
       @save_operations << Operation.new("Delete", type, obj)
     else
-      raise "You cannot delete a non-tracked entity"
+      raise OData::NotSupportedError.new "You cannot delete a non-tracked entity"
     end
   end
 
   # Queues an object for update.  To actually update it on the server, you must call save_changes as well.
   #
-  # ==== Required Attributes
-  # - obj: The object to queue for update
+  # @param [Object] obj the object to queue for update
   #
-  # Note: This method will throw an exception if the +obj+ isn't a tracked entity
+  # @raise [NotSupportedError] if the `obj` isn't a tracked entity
   def update_object(obj)
     type = obj.class.to_s
     if obj.respond_to?(:__metadata) && !obj.send(:__metadata).nil?
       @save_operations << Operation.new("Update", type, obj)
     else
-      raise "You cannot update a non-tracked entity"
+      raise OData::NotSupportedError.new "You cannot update a non-tracked entity"
     end
   end
 
@@ -79,22 +76,28 @@ class Service
 
     result = nil
 
-    if @save_operations.length == 1
-      result = single_save(@save_operations[0])
-    else
-      result = batch_save(@save_operations)
-    end
+    begin
+      if @save_operations.length == 1
+        result = single_save(@save_operations[0])
+      else
+        result = batch_save(@save_operations)
+      end
 
-    # TODO: We should probably perform a check here
-    # to make sure everything worked before clearing it out
-    @save_operations.clear
+      # TODO: We should probably perform a check here
+      # to make sure everything worked before clearing it out
+      @save_operations.clear
 
-    return result
+      return result
+    rescue Exception => e
+      handle_exception(e)
+    end
   end
 
-  # Performs query operations (Read) against the server, returns an array of record instances.
+  # Performs query operations (Read) against the server.
+  # Typically this returns an array of record instances, except in the case of count queries
   def execute
     result = RestClient::Resource.new(build_query_uri, @rest_options).get
+    return Integer(result) if result =~ /^\d+$/
     handle_collection_result(result)
   end
 
@@ -118,7 +121,7 @@ class Service
     end
   end
 
-  # Retrieves the next resultset of a partial result (if any). Does not honor the :eager_partial option.
+  # Retrieves the next resultset of a partial result (if any). Does not honor the `:eager_partial` option.
   def next
     return if not partial?
     handle_partial
@@ -131,14 +134,13 @@ class Service
 
   # Lazy loads a navigation property on a model
   #
-  # ==== Required Attributes
-  # - obj: The object to fill
-  # - nav_prop: The navigation property to fill
+  # @param [Object] obj the object to fill
+  # @param [String] nav_prop the navigation property to fill
   #
-  # Note: This method will throw an exception if the +obj+ isn't a tracked entity
-  # Note: This method will throw an exception if the +nav_prop+ isn't a valid navigation property
+  # @raise [NotSupportedError] if the `obj` isn't a tracked entity
+  # @raise [ArgumentError] if the `nav_prop` isn't a valid navigation property
   def load_property(obj, nav_prop)
-    raise ArgumentError, "You cannot load a property on an entity that isn't tracked" if obj.send(:__metadata).nil?
+    raise NotSupportedError, "You cannot load a property on an entity that isn't tracked" if obj.send(:__metadata).nil?
     raise ArgumentError, "'#{nav_prop}' is not a valid navigation property" unless obj.respond_to?(nav_prop.to_sym)
     raise ArgumentError, "'#{nav_prop}' is not a valid navigation property" unless @class_metadata[obj.class.to_s][nav_prop].nav_prop
     results = RestClient::Resource.new(build_load_property_uri(obj, nav_prop), @rest_options).get
@@ -148,15 +150,17 @@ class Service
 
   # Adds a child object to a parent object's collection
   #
-  # ==== Required Attributes
-  # - parent: The parent object
-  # - nav_prop: The name of the navigation property to add the child to
-  # - child: The child object
+  # @param [Object] parent the parent object
+  # @param [String] nav_prop the name of the navigation property to add the child to
+  # @param [Object] child the child object
+  # @raise [NotSupportedError] if the `parent` isn't a tracked entity
+  # @raise [ArgumentError] if the `nav_prop` isn't a valid navigation property
+  # @raise [NotSupportedError] if the `child` isn't a tracked entity
   def add_link(parent, nav_prop, child)
-    raise ArgumentError, "You cannot add a link on an entity that isn't tracked (#{parent.class})" if parent.send(:__metadata).nil?
+    raise NotSupportedError, "You cannot add a link on an entity that isn't tracked (#{parent.class})" if parent.send(:__metadata).nil?
     raise ArgumentError, "'#{nav_prop}' is not a valid navigation property for #{parent.class}" unless parent.respond_to?(nav_prop.to_sym)
     raise ArgumentError, "'#{nav_prop}' is not a valid navigation property for #{parent.class}" unless @class_metadata[parent.class.to_s][nav_prop].nav_prop
-    raise ArgumentError, "You cannot add a link on a child entity that isn't tracked (#{child.class})" if child.send(:__metadata).nil?
+    raise NotSupportedError, "You cannot add a link on a child entity that isn't tracked (#{child.class})" if child.send(:__metadata).nil?
     @save_operations << Operation.new("AddLink", nav_prop, parent, child)
   end
 
@@ -179,16 +183,16 @@ class Service
     @has_partial = false
     @next_uri = nil
   end
-  
+
   def set_namespaces
     @edmx = Nokogiri::XML(RestClient::Resource.new(build_metadata_uri, @rest_options).get)
-    @ds_namespaces = { 
+    @ds_namespaces = {
       "m" => "http://schemas.microsoft.com/ado/2007/08/dataservices/metadata",
       "edmx" => "http://schemas.microsoft.com/ado/2007/06/edmx",
       "ds" => "http://schemas.microsoft.com/ado/2007/08/dataservices",
       "atom" => "http://www.w3.org/2005/Atom"
     }
-    
+
     # Get the edm namespace from the edmx
     edm_ns = @edmx.xpath("edmx:Edmx/edmx:DataServices/*", @namespaces).first.namespaces['xmlns'].to_s
     @ds_namespaces.merge! "edm" => edm_ns
@@ -232,7 +236,7 @@ class Service
       entity_type = c["EntityType"]
       @collections[c["Name"]] = { :edmx_type => entity_type, :type => convert_to_local_type(entity_type) }
     end
-    
+
     build_function_imports
   end
 
@@ -258,9 +262,9 @@ class Service
           parameters[p["Name"]] = p["Type"]
         end
       end
-      @function_imports[f["Name"]] = { 
-        :http_method => http_method, 
-        :return_type => return_type, 
+      @function_imports[f["Name"]] = {
+        :http_method => http_method,
+        :return_type => return_type,
         :inner_return_type => inner_return_type,
         :parameters => parameters }
     end
@@ -294,7 +298,7 @@ class Service
     end
     metadata
   end
-  
+
   # Handle parsing of OData Atom result and return an array of Entry classes
   def handle_collection_result(result)
     results = build_classes_from_result(result)
@@ -303,7 +307,18 @@ class Service
     end
     results
   end
-  
+
+  # Handles errors from the OData service
+  def handle_exception(e)
+    raise e unless e.response
+
+    code = e.http_code
+    error = Nokogiri::XML(e.response)
+
+    message = error.xpath("m:error/m:message", @ds_namespaces).first.content
+    raise "HTTP Error #{code}: #{message}"
+  end
+
   # Loops through the standard properties (non-navigation) for a given class and returns the appropriate list of methods
   def collect_properties(klass_name, element, doc)
     props = element.xpath(".//edm:Property", @ds_namespaces)
@@ -318,7 +333,7 @@ class Service
     end
     methods
   end
-  
+
   # Similar to +collect_properties+, but handles the navigation properties
   def collect_navigation_properties(klass_name, element, doc)
     nav_props = element.xpath(".//edm:NavigationProperty", @ds_namespaces)
@@ -329,14 +344,14 @@ class Service
   # Helper to loop through a result and create an instance for each entity in the results
   def build_classes_from_result(result)
     doc = Nokogiri::XML(result)
-    
+
     is_links = doc.at_xpath("/ds:links", @ds_namespaces)
     return parse_link_results(doc) if is_links
-    
+
     entries = doc.xpath("//atom:entry[not(ancestor::atom:entry)]", @ds_namespaces)
-    
+
     extract_partial(doc)
-    
+
     results = []
     entries.each do |entry|
       results << entry_to_class(entry)
@@ -348,24 +363,24 @@ class Service
   def entry_to_class(entry)
     # Retrieve the class name from the fully qualified name (the last string after the last dot)
     klass_name = entry.xpath("./atom:category/@term", @ds_namespaces).to_s.split('.')[-1]
-    
+
     # Is the category missing? See if there is a title that we can use to build the class
     if klass_name.nil?
       title = entry.xpath("./atom:title", @ds_namespaces).first
       return nil if title.nil?
       klass_name = title.content.to_s
     end
-        
+
     return nil if klass_name.nil?
 
-    # If we are working against a child (inline) entry, we need to use the more generic xpath because a child entry WILL 
+    # If we are working against a child (inline) entry, we need to use the more generic xpath because a child entry WILL
     # have properties that are ancestors of m:inline. Check if there is an m:inline child to determine the xpath query to use
     has_inline = entry.xpath(".//m:inline", @ds_namespaces).any?
     properties_xpath = has_inline ? ".//m:properties[not(ancestor::m:inline)]/*" : ".//m:properties/*"
     properties = entry.xpath(properties_xpath, @ds_namespaces)
 
     klass = @classes[qualify_class_name(klass_name)].new
-    
+
     # Fill metadata
     meta_id = entry.xpath("./atom:id", @ds_namespaces)[0].content
     klass.send :__metadata=, { :uri => meta_id }
@@ -375,7 +390,7 @@ class Service
       prop_name = prop.name
       klass.send "#{prop_name}=", parse_value(prop)
     end
-    
+
     # Fill properties represented outside of the properties collection
     @class_metadata[qualify_class_name(klass_name)].select { |k,v| v.fc_keep_in_content == false }.each do |k, meta|
       if meta.fc_target_path == "SyndicationTitle"
@@ -386,13 +401,13 @@ class Service
         klass.send "#{meta.name}=", summary.content
       end
     end
-    
+
     inline_links = entry.xpath("./atom:link[m:inline]", @ds_namespaces)
-    
+
     for link in inline_links
       inline_entries = link.xpath(".//atom:entry", @ds_namespaces)
 
-      # TODO: Use the metadata's associations to determine the multiplicity instead of this "hack"  
+      # TODO: Use the metadata's associations to determine the multiplicity instead of this "hack"
       property_name = link.attributes['title'].to_s
       if inline_entries.length == 1 && singular?(property_name)
         inline_klass = build_inline_class(klass, inline_entries[0], property_name)
@@ -412,17 +427,17 @@ class Service
         klass.send "#{property_name}=", inline_classes
       end
     end
-    
+
     klass
   end
-  
+
   # Tests for and extracts the next href of a partial
   def extract_partial(doc)
     next_links = doc.xpath('//atom:link[@rel="next"]', @ds_namespaces)
     @has_partial = next_links.any?
     @next_uri = next_links[0]['href'] if @has_partial
   end
-  
+
   def handle_partial
     if @next_uri
       result = RestClient::Resource.new(@next_uri, @rest_options).get
@@ -430,7 +445,7 @@ class Service
     end
     results
   end
-  
+
   # Handle link results
   def parse_link_results(doc)
     uris = doc.xpath("/ds:links/ds:uri", @ds_namespaces)
@@ -440,7 +455,7 @@ class Service
       results << URI.parse(link)
     end
     results
-  end   
+  end
 
   # Build URIs
   def build_metadata_uri
@@ -470,7 +485,7 @@ class Service
   def build_batch_uri
     uri = "#{@uri}/$batch"
     uri << "?#{@additional_params.to_query}" unless @additional_params.empty?
-    uri    
+    uri
   end
   def build_load_property_uri(obj, property)
     uri = obj.__metadata[:uri]
@@ -483,11 +498,11 @@ class Service
     uri << "?#{params.to_query}" unless params.empty?
     uri
   end
-  
+
   def build_inline_class(klass, entry, property_name)
     # Build the class
     inline_klass = entry_to_class(entry)
-  
+
     # Add the property
     klass.send "#{property_name}=", inline_klass
   end
@@ -543,20 +558,20 @@ class Service
   def generate_guid
     rand(36**12).to_s(36).insert(4, "-").insert(9, "-")
   end
-  def batch_save(operations)  
+  def batch_save(operations)
     batch_num = generate_guid
     changeset_num = generate_guid
     batch_uri = build_batch_uri
-    
+
     body = build_batch_body(operations, batch_num, changeset_num)
     result = RestClient::Resource.new( batch_uri, @rest_options).post body, {:content_type => "multipart/mixed; boundary=batch_#{batch_num}"}
 
-    # TODO: More result validation needs to be done.  
+    # TODO: More result validation needs to be done.
     # The result returns HTTP 202 even if there is an error in the batch
     return (result.code == 202)
   end
   def build_batch_body(operations, batch_num, changeset_num)
-    # Header    
+    # Header
     body = "--batch_#{batch_num}\n"
     body << "Content-Type: multipart/mixed;boundary=changeset_#{changeset_num}\n\n"
 
@@ -565,51 +580,51 @@ class Service
       body << build_batch_operation(operation, changeset_num)
       body << "\n"
     end
-        
-    # Footer    
+
+    # Footer
     body << "\n\n--changeset_#{changeset_num}--\n"
     body << "--batch_#{batch_num}--"
-    
+
     return body
   end
   def build_batch_operation(operation, changeset_num)
     accept_headers = "Accept-Charset: utf-8\n"
     accept_headers << "Content-Type: application/json;charset=utf-8\n" unless operation.kind == "Delete"
     accept_headers << "\n"
-  
+
     content = "--changeset_#{changeset_num}\n"
     content << "Content-Type: application/http\n"
     content << "Content-Transfer-Encoding: binary\n\n"
-    
-    if operation.kind == "Add"      
+
+    if operation.kind == "Add"
       save_uri = "#{@uri}/#{operation.klass_name}"
       json_klass = operation.klass.to_json(:type => :add)
-      
+
       content << "POST #{save_uri} HTTP/1.1\n"
       content << accept_headers
       content << json_klass
     elsif operation.kind == "Update"
       update_uri = operation.klass.send(:__metadata)[:uri]
       json_klass = operation.klass.to_json
-      
+
       content << "PUT #{update_uri} HTTP/1.1\n"
       content << accept_headers
       content << json_klass
     elsif operation.kind == "Delete"
       delete_uri = operation.klass.send(:__metadata)[:uri]
-      
+
       content << "DELETE #{delete_uri} HTTP/1.1\n"
       content << accept_headers
     elsif
       save_uri = build_add_link_uri(operation)
       json_klass = operation.child_klass.to_json(:type => :link)
-      
+
       content << "POST #{save_uri} HTTP/1.1\n"
       content << accept_headers
       content << json_klass
       link_child_to_parent(operation)
     end
-      
+
     return content
   end
 
@@ -628,24 +643,24 @@ class Service
   end
 
   # Field Converters
-  
+
   # Handles parsing datetimes from a string
   def parse_date(sdate)
     # Assume this is UTC if no timezone is specified
     sdate = sdate + "Z" unless sdate.match(/Z|([+|-]\d{2}:\d{2})$/)
-    
+
     # This is to handle older versions of Ruby (e.g. ruby 1.8.7 (2010-12-23 patchlevel 330) [i386-mingw32])
     # See http://makandra.com/notes/1017-maximum-representable-value-for-a-ruby-time-object
     # In recent versions of Ruby, Time has a much larger range
     begin
-      result = Time.parse(sdate)  
+      result = Time.parse(sdate)
     rescue ArgumentError
       result = DateTime.parse(sdate)
     end
-    
+
     return result
   end
-  
+
   # Parses a value into the proper type based on an xml property element
   def parse_value(property_xml)
     property_type = property_xml.attr('type')
@@ -673,7 +688,7 @@ class Service
     # If we can't parse the value, just return the element's content
     property_xml.content
   end
-  
+
   # Parses a value into the proper type based on a specified return type
   def parse_primative_type(value, return_type)
     return value.to_i if return_type == Fixnum
@@ -681,7 +696,7 @@ class Service
     return parse_date(value.to_s) if return_type == Time
     return value.to_s
   end
-  
+
   # Converts an edm type (string) to a ruby type
   def edm_to_ruby_type(edm_type)
     return String if edm_type =~ /Edm.String/
@@ -690,30 +705,30 @@ class Service
     return Time if edm_type =~ /Edm.DateTime/
     return String
   end
-  
+
   # Method Missing Handlers
-  
+
   # Executes an import function
   def execute_import_function(name, *args)
     func = @function_imports[name]
-    
+
     # Check the args making sure that more weren't passed in than the function needs
     param_count = func[:parameters].nil? ? 0 : func[:parameters].count
     arg_count = args.nil? ? 0 : args[0].count
     if arg_count > param_count
       raise ArgumentError, "wrong number of arguments (#{arg_count} for #{param_count})"
     end
-    
+
     # Convert the parameters to a hash
     params = {}
     func[:parameters].keys.each_with_index { |key, i| params[key] = args[0][i] } unless func[:parameters].nil?
-    
+
     function_uri = build_function_import_uri(name, params)
     result = RestClient::Resource.new(function_uri, @rest_options).send(func[:http_method].downcase, {})
-    
+
     # Is this a 204 (No content) result?
     return true if result.code == 204
-    
+
     # No? Then we need to parse the results. There are 4 kinds...
     if func[:return_type] == Array
       # a collection of entites
@@ -726,19 +741,19 @@ class Service
       end
       return results
     end
-    
+
     # a single entity
     if @classes.include?(func[:return_type].to_s)
       entry = Nokogiri::XML(result).xpath("atom:entry[not(ancestor::atom:entry)]", @ds_namespaces)
       return entry_to_class(entry)
     end
-    
+
     # or a single native type
     unless func[:return_type].nil?
       e = Nokogiri::XML(result).xpath("/*").first
       return parse_primative_type(e.content, func[:return_type])
     end
-    
+
     # Nothing could be parsed, so just return if we got a 200 or not
     return (result.code == 200)
   end

data/lib/ruby_odata/version.rb

@@ -1,3 +1,5 @@
+# The ruby_odata namespace
 module OData
-  VERSION = "0.1.0"
+  # The current version of ruby_odata
+  VERSION = "0.1.1"
 end

data/lib/ruby_odata.rb

@@ -1,21 +1,23 @@
 lib =  File.dirname(__FILE__)
 
-$: << lib + '/ruby_odata/'
-require 'rubygems'
-require 'active_support' # Used for serializtion to JSON
-require 'active_support/inflector'
-require 'active_support/core_ext'
-require 'cgi'
-require 'rest_client'
-require 'nokogiri'
-require 'bigdecimal'
-require 'bigdecimal/util'
-require 'backports'
+$: << lib + "/ruby_odata/"
+require "rubygems"
+require "i18n"
+require "active_support" # Used for serializtion to JSON
+require "active_support/inflector"
+require "active_support/core_ext"
+require "cgi"
+require "rest_client"
+require "nokogiri"
+require "bigdecimal"
+require "bigdecimal/util"
+require "backports"
 
-require lib + '/ruby_odata/association'
-require lib + '/ruby_odata/property_metadata'
-require lib + '/ruby_odata/query_builder'
-require lib + '/ruby_odata/class_builder'
-require lib + '/ruby_odata/operation'
-require lib + '/ruby_odata/service'
-require lib + '/ruby_odata/helpers'
+require lib + "/ruby_odata/exceptions"
+require lib + "/ruby_odata/association"
+require lib + "/ruby_odata/property_metadata"
+require lib + "/ruby_odata/query_builder"
+require lib + "/ruby_odata/class_builder"
+require lib + "/ruby_odata/operation"
+require lib + "/ruby_odata/service"
+require lib + "/ruby_odata/helpers"

data/ruby_odata.gemspec

@@ -14,18 +14,22 @@ Gem::Specification.new do |s|
 
   s.rubyforge_project = "ruby-odata"
 
-  s.add_dependency('activesupport', '>= 2.3.5')
-  s.add_dependency('rest-client', '>= 1.5.1')
-  s.add_dependency('nokogiri', '>= 1.4.2')
-  s.add_dependency('backports', "~> 2.3.0")
-  
-  s.add_development_dependency('rake', '~> 0.8.7')
-  s.add_development_dependency('rspec', '~> 2.5.0')
-  s.add_development_dependency('cucumber', '~> 0.10.2')
-  s.add_development_dependency('pickle', '~> 0.4.10')
-  s.add_development_dependency('faker', '~> 0.9.5')
-  s.add_development_dependency('machinist', '~> 1.0.6')
-  s.add_development_dependency('webmock', '~> 1.6.2')
+  s.add_dependency("i18n", "~> 0.6.0")
+  s.add_dependency("activesupport", ">= 3.0.0")
+  s.add_dependency("rest-client", ">= 1.5.1")
+  s.add_dependency("nokogiri", ">= 1.4.2")
+  s.add_dependency("backports", "~> 2.3.0")
+
+  s.add_development_dependency("rake", "0.9.2")
+  s.add_development_dependency("rspec", "~> 2.11.0")
+  s.add_development_dependency("cucumber", "~> 1.2.1")
+  s.add_development_dependency("pickle", "~> 0.4.11")
+  s.add_development_dependency("machinist", "~> 2.0")
+  s.add_development_dependency("webmock", "~> 1.8.8")
+  s.add_development_dependency("guard", "~> 1.3.0")
+  s.add_development_dependency("guard-rspec", "~> 1.2.1")
+  s.add_development_dependency("guard-cucumber", "~> 1.2.0")
+  s.add_development_dependency("vcr", "~> 2.2.4")
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")