odata4 0.7.0

data/Rakefile

@@ -0,0 +1,7 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+

data/TODO.md

@@ -0,0 +1,55 @@
+# OData V4 To-Do
+
+This is a non-complete list of things that need to be done in order to achieve OData V4 compatibility. It will be updated regularly to keep track with current development.
+
+## Tasks
+
+[x] `DataServiceVersion` headers changes to `OData-Version`
+[x] Atom: update namespace URIs
+[x] Implement JSON data format
+  [x] with batch processing
+[ ] Implement missing/new OData V4 types
+  [x] `Edm.Date` (V4/RESO)
+  [ ] `Edm.Duration` (V4)
+  [x] `Edm.TimeOfDay` (V4/RESO)
+  [x] `Edm.EnumType` (V4/RESO)
+  [ ] `Edm.Geography` subtypes (RESO)
+    [x] `Edm.GeographyPoint`
+    [ ] `Edm.GeographyMultiPoint`
+    [x] `Edm.GeographyLineString`
+    [ ] `Edm.GeographyMultiLineString`
+    [x] `Edm.GeographyPolygon` (see note below)
+        [ ] Support for holes
+        [ ] Support for other serialization formats
+    [ ] `Edm.GeopgrahyMultiPolygon`
+
+##### NOTE
+
+Due to the lack of library support for GeoXML/GML in Ruby, Geography support is somewhat limited. For instance, [there are more than 3 different ways to represent a polygon in GML][gml-madness], all of which are equivalent and interchangeable. However, due to the lack of GML libraries, we currently only support a single serialization format (`<gml:LinearRing>` with `<gml:pos>` elements, see [polygon_spec.rb][polygon_spec]).
+
+[gml-madness]: http://erouault.blogspot.com/2014/04/gml-madness.html
+[polygon_spec]: spec/odata/v4/properties/geography/polygon_spec.rb
+
+[x] Changes to `NavigationProperty`
+  [x] No more associations (but we probably still need a proxy class)
+  [x] New `Type` property
+  [x] New `Nullable` property
+  [x] New `Partner` property
+  [ ] New `ContainsTarget` property
+
+[ ] Changes to querying
+  [x] `$count=true` replaces `$inlinecount=allpages`
+  [x] New `$search` param for fulltext search
+  [x] String functions
+  [x] Date/time functions
+  [x] Geospatial functions
+  [x] [Lambda operators][1]
+
+[ ] Logging
+
+[1]: http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part2-url-conventions/odata-v4.0-errata02-os-part2-url-conventions-complete.html#_Toc406398149
+
+## Questions / Thoughts
+
+[ ] Use standard JSON parser or OJ (or offer choice?)
+[x] Continue to support XML data format (JSON is recommended for V4)? -> We'll support both, ATOM first, JSON to be added later.

data/lib/odata4.rb

@@ -0,0 +1,37 @@
+require 'uri'
+require 'date'
+require 'time'
+require 'bigdecimal'
+require 'nokogiri'
+require 'typhoeus'
+require 'andand'
+require 'json'
+
+# require 'active_support'
+# require 'active_support/core_ext'
+# require 'active_support/concern'
+
+require 'odata4/version'
+require 'odata4/property_registry'
+require 'odata4/property'
+require 'odata4/properties'
+require 'odata4/navigation_property'
+require 'odata4/complex_type'
+require 'odata4/enum_type'
+require 'odata4/entity'
+require 'odata4/entity_set'
+require 'odata4/query/criteria'
+require 'odata4/query/result'
+require 'odata4/query/in_batches'
+require 'odata4/query'
+require 'odata4/service'
+require 'odata4/service_registry'
+
+require 'odata4/railtie' if defined?(::Rails)
+
+# The OData4 gem provides a convenient way to interact with OData4 services from
+# Ruby. Please look to the {file:README.md README} for how to get started using
+# the OData4 gem.
+module OData4
+  # Your code goes here...
+end

data/lib/odata4/complex_type.rb

@@ -0,0 +1,76 @@
+require 'odata4/complex_type/property'
+
+module OData4
+  # ComplexTypes are used in OData4 to either encapsulate richer data types for
+  # use as Entity properties. ComplexTypes are composed of properties the same
+  # way that Entities are and, so, the interface for working with the various
+  # properties of a ComplexType mimics that of Entities.
+  class ComplexType
+    # Creates a new ComplexType based on the supplied options.
+    # @param type_xml [Nokogiri::XML::Element]
+    # @param service [OData4::Service]
+    # @return [self]
+    def initialize(type_definition, service)
+      @type_definition = type_definition
+      @service         = service
+    end
+
+    # The name of the ComplexType
+    # @return [String]
+    def name
+      @name ||= type_definition.attributes['Name'].value
+    end
+
+    # Returns the namespaced type for the ComplexType.
+    # @return [String]
+    def type
+      "#{namespace}.#{name}"
+    end
+
+    # Returns the namespace this ComplexType belongs to.
+    # @return [String]
+    def namespace
+      @namespace ||= service.namespace
+    end
+
+    # Returns this ComplexType's properties.
+    # @return [Hash<String, OData4::Property>]
+    def properties
+      @properties ||= collect_properties
+    end
+
+    # Returns a list of this ComplexType's property names.
+    # @return [Array<String>]
+    def property_names
+      @property_names ||= properties.keys
+    end
+
+    # Returns the property class that implements this `ComplexType`.
+    # @return [Class < OData4::ComplexType::Property]
+    def property_class
+      @property_class ||= lambda { |type, complex_type|
+        klass = Class.new ::OData4::ComplexType::Property
+        klass.send(:define_method, :type) { type }
+        klass.send(:define_method, :complex_type) { complex_type }
+        klass
+      }.call(type, self)
+    end
+
+    private
+
+    def service
+      @service
+    end
+
+    def type_definition
+      @type_definition
+    end
+
+    def collect_properties
+      Hash[type_definition.xpath('./Property').map do |property_xml|
+        property_name, property = service.send(:process_property_from_xml,property_xml)
+        [property_name, property]
+      end]
+    end
+  end
+end

data/lib/odata4/complex_type/property.rb

@@ -0,0 +1,114 @@
+module OData4
+  class ComplexType
+    # Abstract base class for OData4 ComplexTypes
+    # @see [OData4::ComplexType]
+    class Property < OData4::Property
+      def initialize(name, value, options = {})
+        super(name, value, options)
+        init_properties
+      end
+
+      # Returns the property value, properly typecast
+      # @return [Hash, nil]
+      def value
+        if allows_nil? && properties.values.all?(&:nil?)
+          nil
+        else
+          Hash[properties.map { |key, value| [key, value.value] }]
+        end
+      end
+
+      # Sets the property value
+      # @params new_value [Hash]
+      def value=(new_value)
+        validate(new_value)
+        if new_value.nil?
+          property_names.each { |name| self[name] = nil }
+        else
+          property_names.each { |name| self[name] = new_value[name] }
+        end
+      end
+
+      # Returns a list of this ComplexType's property names.
+      # @return [Array<String>]
+      def property_names
+        @property_names ||= properties.keys
+      end
+
+      # Returns the value of the requested property.
+      # @param property_name [to_s]
+      # @return [*]
+      def [](property_name)
+        properties[property_name.to_s].value
+      end
+
+      # Sets the value of the named property.
+      # @param property_name [to_s]
+      # @param value [*]
+      # @return [*]
+      def []=(property_name, value)
+        properties[property_name.to_s].value = value
+      end
+
+      # Returns the XML representation of the property to the supplied XML
+      # builder.
+      # @param xml_builder [Nokogiri::XML::Builder]
+      def to_xml(xml_builder)
+        attributes = {
+            'metadata:type' => type,
+        }
+
+        xml_builder['data'].send(name.to_sym, attributes) do
+          properties.each do |name, property|
+            property.to_xml(xml_builder)
+          end
+        end
+      end
+
+      # Creates a new property instance from an XML element
+      # @param property_xml [Nokogiri::XML::Element]
+      # @param options [Hash]
+      # @return [OData4::Property]
+      def self.from_xml(property_xml, options = {})
+        nodes = property_xml.element_children
+        props = Hash[nodes.map { |el| [el.name, el.content] }]
+        new(property_xml.name, props.to_json, options)
+      end
+
+      private
+
+      def complex_type
+        raise NotImplementedError, 'Subclass must override'
+      end
+
+      def properties
+        @properties
+      end
+
+      def init_properties
+        @properties = complex_type.send(:collect_properties)
+        set_properties(JSON.parse(@value)) unless @value.nil?
+      end
+
+      def set_properties(new_properties)
+        property_names.each do |prop_name|
+          self[prop_name] = new_properties[prop_name]
+        end
+      end
+
+      def validate(value)
+        return if value.nil? && allows_nil?
+        raise ArgumentError, 'Value must be a Hash' unless value.is_a?(Hash)
+        value.keys.each do |name|
+          unless property_names.include?(name) || name =~ /@odata/
+            raise ArgumentError, "Invalid property #{name}"
+          end
+        end
+      end
+
+      def validate_options(options)
+        raise ArgumentError, 'Type is required' unless options[:type]
+      end
+    end
+  end
+end

data/lib/odata4/entity.rb

@@ -0,0 +1,319 @@
+module OData4
+  # An OData4::Entity represents a single record returned by the service. All
+  # Entities have a type and belong to a specific namespace. They are written
+  # back to the service via the EntitySet they came from. OData4::Entity
+  # instances should not be instantiated directly; instead, they should either
+  # be read or instantiated from their respective OData4::EntitySet.
+  class Entity
+    # The Entity type name
+    attr_reader :type
+    # The OData4::Service's namespace
+    attr_reader :namespace
+    # The OData4::Service's identifying name
+    attr_reader :service_name
+    # The entity set this entity belongs to
+    attr_reader :entity_set
+    # List of errors on entity
+    attr_reader :errors
+
+    PROPERTY_NOT_LOADED = :not_loaded
+
+    XML_NAMESPACES = {
+      'xmlns'           => 'http://www.w3.org/2005/Atom',
+      'xmlns:data'      => 'http://docs.oasis-open.org/odata/ns/data',
+      'xmlns:metadata'  => 'http://docs.oasis-open.org/odata/ns/metadata',
+      'xmlns:georss'    => 'http://www.georss.org/georss',
+      'xmlns:gml'       => 'http://www.opengis.net/gml',
+    }.freeze
+
+    # Initializes a bare Entity
+    # @param options [Hash]
+    def initialize(options = {})
+      @id = options[:id]
+      @type = options[:type]
+      @namespace = options[:namespace]
+      @service_name = options[:service_name]
+      @entity_set = options[:entity_set]
+      @context = options[:context]
+      @links = options[:links]
+      @errors = []
+    end
+
+    # Returns name of Entity from Service specified type.
+    # @return [String]
+    def name
+      @name ||= type.gsub(/#{namespace}\./, '')
+    end
+
+    # Returns context URL for this entity
+    # @return [String]
+    def context
+      @context ||= context_url
+    end
+
+    # Get property value
+    # @param property_name [to_s]
+    # @return [*]
+    def [](property_name)
+      if get_property(property_name).is_a?(::OData4::ComplexType::Property)
+        get_property(property_name)
+      else
+        get_property(property_name).value
+      end
+    end
+
+    # Set property value
+    # @param property_name [to_s]
+    # @param value [*]
+    def []=(property_name, value)
+      get_property(property_name).value = value
+    end
+
+    def get_property(property_name)
+      prop_name = property_name.to_s
+      # Property is lazy loaded
+      if properties_xml_value.has_key?(prop_name)
+        property = instantiate_property(prop_name, properties_xml_value[prop_name])
+        set_property(prop_name, property.dup)
+        properties_xml_value.delete(prop_name)
+      end
+
+      if properties.has_key? prop_name
+        properties[prop_name]
+      elsif navigation_properties.has_key? prop_name
+        navigation_properties[prop_name]
+      else
+        raise ArgumentError, "Unknown property: #{property_name}"
+      end
+    end
+
+    def property_names
+      [
+        @properties_xml_value.andand.keys,
+        @properties.andand.keys
+      ].compact.flatten
+    end
+
+    def navigation_property_names
+      navigation_properties.keys
+    end
+
+    def navigation_properties
+      @navigation_properties ||= links.keys.map do |nav_name|
+        [
+          nav_name,
+          OData4::NavigationProperty::Proxy.new(self, nav_name)
+        ]
+      end.to_h
+    end
+
+    # Links to other OData4 entitites
+    # @return [Hash]
+    def links
+      @links ||= service.navigation_properties[name].map do |nav_name, details|
+        [
+          nav_name,
+          { type: details.nav_type, href: "#{id}/#{nav_name}" }
+        ]
+      end.to_h
+    end
+
+    # Create Entity with provided properties and options.
+    # @param new_properties [Hash]
+    # @param options [Hash]
+    # @param [OData4::Entity]
+    def self.with_properties(new_properties = {}, options = {})
+      entity = OData4::Entity.new(options)
+      entity.instance_eval do
+        service.properties_for_entity(name).each do |property_name, instance|
+          set_property(property_name, instance)
+        end
+
+        new_properties.each do |property_name, property_value|
+          self[property_name] = property_value
+        end
+      end
+      entity
+    end
+
+    # Create Entity from JSON document with provided options.
+    # @param json [Hash|to_s]
+    # @param options [Hash]
+    # @return [OData4::Entity]
+    def self.from_json(json, options = {})
+      return nil if json.nil?
+      json = JSON.parse(json.to_s) unless json.is_a?(Hash)
+      metadata = extract_metadata(json)
+      options.merge!(context: metadata['@odata.context'])
+      entity = with_properties(json, options)
+      process_metadata(entity, metadata)
+      entity
+    end
+
+    # Create Entity from XML document with provided options.
+    # @param xml_doc [Nokogiri::XML]
+    # @param options [Hash]
+    # @return [OData4::Entity]
+    def self.from_xml(xml_doc, options = {})
+      return nil if xml_doc.nil?
+      entity = OData4::Entity.new(options)
+      process_properties(entity, xml_doc)
+      process_links(entity, xml_doc)
+      entity
+    end
+
+    # Converts Entity to its XML representation.
+    # @return [String]
+    def to_xml
+      namespaces = XML_NAMESPACES.merge('xml:base' => service.service_url)
+      builder = Nokogiri::XML::Builder.new do |xml|
+        xml.entry(namespaces) do
+          xml.category(term: "#{namespace}.#{type}",
+                       scheme: 'http://docs.oasis-open.org/odata/ns/scheme')
+          xml.author { xml.name }
+
+          xml.content(type: 'application/xml') do
+            xml['metadata'].properties do
+              property_names.each do |name|
+                next if name == primary_key
+                get_property(name).to_xml(xml)
+              end
+            end
+          end
+        end
+      end
+      builder.to_xml
+    end
+
+    # Converts Entity to its JSON representation.
+    # @return [String]
+    def to_json
+      # TODO: add @odata.context
+      to_hash.to_json
+    end
+
+    # Converts Entity to a hash.
+    # @return [Hash]
+    def to_hash
+      property_names.map do |name|
+        [name, get_property(name).json_value]
+      end.to_h
+    end
+
+    # Returns the canonical URL for this entity
+    # @return [String]
+    def id
+      @id ||= lambda {
+        entity_set = self.entity_set.andand.name
+        entity_set ||= context.split('#').last.split('/').first
+        "#{entity_set}(#{self[primary_key]})"
+      }.call
+    end
+
+    # Returns the primary key for the Entity.
+    # @return [String]
+    def primary_key
+      service.primary_key_for(name)
+    end
+
+    def is_new?
+      self[primary_key].nil?
+    end
+
+    def any_errors?
+      !errors.empty?
+    end
+
+    def service
+      @service ||= OData4::ServiceRegistry[service_name]
+    end
+
+    private
+
+    def instantiate_property(property_name, value_xml)
+      value_type = service.get_property_type(name, property_name)
+      klass = ::OData4::PropertyRegistry[value_type]
+
+      if klass.nil?
+        raise RuntimeError, "Unknown property type: #{value_type}"
+      else
+        klass.from_xml(value_xml)
+      end
+    end
+
+    def properties
+      @properties ||= {}
+    end
+
+    def properties_xml_value
+      @properties_xml_value ||= {}
+    end
+
+    # Computes the entity's canonical context URL
+    def context_url
+      "#{service.service_url}/$metadata##{entity_set.name}/$entity"
+    end
+
+    def set_property(name, property)
+      properties[name.to_s] = property
+    end
+
+    # Instantiating properties takes time, so we can lazy load properties by passing xml_value and lookup when needed
+    def set_property_lazy_load(name, xml_value )
+      properties_xml_value[name.to_s] = xml_value
+    end
+
+    def self.process_properties(entity, xml_doc)
+      entity.instance_eval do
+        unless instance_variable_get(:@context)
+          context = xml_doc.xpath('/entry').first.andand['context']
+          instance_variable_set(:@context, context)
+        end
+
+        xml_doc.xpath('./content/properties/*').each do |property_xml|
+          # Doing lazy loading here because instantiating each object takes a long time
+          set_property_lazy_load(property_xml.name, property_xml)
+        end
+      end
+    end
+
+    def self.process_links(entity, xml_doc)
+      entity.instance_eval do
+        new_links = instance_variable_get(:@links) || {}
+        service.navigation_properties[name].each do |nav_name, details|
+          xml_doc.xpath("./link[@title='#{nav_name}']").each do |node|
+            next if node.attributes['type'].nil?
+            next unless node.attributes['type'].value =~ /^application\/atom\+xml;type=(feed|entry)$/i
+            link_type = node.attributes['type'].value =~ /type=entry$/i ? :entity : :collection
+            new_links[nav_name] = {
+              type: link_type,
+              href: node.attributes['href'].value
+            }
+          end
+        end
+        instance_variable_set(:@links, new_links)
+      end
+    end
+
+    def self.extract_metadata(json)
+      metadata = json.select { |key, val| key =~ /@odata/ }
+      json.delete_if { |key, val| key =~ /@odata/ }
+      metadata
+    end
+
+    def self.process_metadata(entity, metadata)
+      entity.instance_eval do
+        new_links = instance_variable_get(:@links) || {}
+        service.navigation_properties[name].each do |nav_name, details|
+          href = metadata["#{nav_name}@odata.navigationLink"]
+          next if href.nil?
+          new_links[nav_name] = {
+            type: details.nav_type,
+            href: href
+          }
+        end
+        instance_variable_set(:@links, new_links) unless new_links.empty?
+      end
+    end
+  end
+end