frodo 0.10.0

data/lib/frodo/config.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module Frodo
+  class << self
+    attr_writer :log
+
+    # Returns the current Configuration
+    #
+    # Example
+    #
+    #    Frodo.configuration.username = "username"
+    #    Frodo.configuration.password = "password"
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the Configuration
+    #
+    # Example
+    #
+    #    Frodo.configure do |config|
+    #      config.username = "username"
+    #      config.password = "password"
+    #    end
+    def configure
+      yield configuration
+    end
+
+    def log?
+      @log ||= false
+    end
+
+    def log(message)
+      return unless Frodo.log?
+      configuration.logger.send(configuration.log_level, message)
+    end
+  end
+
+  class Configuration
+    class Option
+      attr_reader :configuration, :name, :options
+
+      def self.define(*args)
+        new(*args).define
+      end
+
+      def initialize(configuration, name, options = {})
+        @configuration = configuration
+        @name = name
+        @options = options
+        @default = options.fetch(:default, nil)
+      end
+
+      def define
+        write_attribute
+        define_method if default_provided?
+        self
+      end
+
+      private
+
+      attr_reader :default
+      alias default_provided? default
+
+      def write_attribute
+        configuration.send :attr_accessor, name
+      end
+
+      def define_method
+        our_default = default
+        our_name    = name
+        configuration.send :define_method, our_name do
+          instance_variable_get(:"@#{our_name}") ||
+            instance_variable_set(
+              :"@#{our_name}",
+              our_default.respond_to?(:call) ? our_default.call : our_default
+            )
+        end
+      end
+    end
+
+    class << self
+      attr_accessor :options
+
+      def option(*args)
+        option = Option.define(self, *args)
+        (self.options ||= []) << option.name
+      end
+    end
+
+    # The OAuth client id
+    option :client_id
+
+    # The OAuth client secret
+    option :client_secret
+
+    option :host, default: 'login.microsoftonline.com'
+
+    option :oauth_token
+    option :refresh_token
+    option :instance_url
+    option :base_path
+
+    # Set this to an object that responds to read, write and fetch and all GET
+    # requests will be cached.
+    option :cache
+
+    # The number of times reauthentication should be tried before failing.
+    option :authentication_retries, default: 3
+
+    # Set to true if you want responses from Dynamics to be gzip compressed.
+    option :compress
+
+    # Faraday request read/open timeout.
+    option :timeout
+
+    # Faraday adapter to use. Defaults to Faraday.default_adapter.
+    option :adapter, default: lambda { Faraday.default_adapter }
+
+    option :proxy_uri, default: lambda { ENV['FRODATA_PROXY_URI'] }
+
+    # A Proc that is called with the response body after a successful authentication.
+    option :authentication_callback
+
+    # Set SSL options
+    option :ssl, default: {}
+
+    # A Hash that is converted to HTTP headers
+    option :request_headers
+
+    # Set a logger for when Frodo.log is set to true, defaulting to STDOUT
+    option :logger, default: ::Logger.new(STDOUT)
+
+    # Set a log level for logging when Frodo.log is set to true, defaulting to :debug
+    option :log_level, default: :debug
+
+    def options
+      self.class.options
+    end
+  end
+end

data/lib/frodo/entity.rb

@@ -0,0 +1,335 @@
+module Frodo
+  # An Frodo::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. Frodo::Entity
+  # instances should not be instantiated directly; instead, they should either
+  # be read or instantiated from their respective Frodo::EntitySet.
+  class Entity
+    # The Entity type name
+    attr_reader :type
+    # The Frodo::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]
+      @service_name = options[:service_name]
+      @entity_set = options[:entity_set]
+      @context = options[:context]
+      @links = options[:links]
+      @errors = []
+    end
+
+    def namespace
+      @namespace ||= type.rpartition('.').first
+    end
+
+    # Returns name of Entity from Service specified type.
+    # @return [String]
+    def name
+      @name ||= type.split('.').last
+    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?(::Frodo::Properties::Complex)
+        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,
+          Frodo::NavigationProperty::Proxy.new(self, nav_name)
+        ]
+      end.to_h
+    end
+
+    # Links to other Frodo entitites
+    # @return [Hash]
+    def links
+      @links ||= schema.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 [Frodo::Entity]
+    def self.with_properties(new_properties = {}, options = {})
+      entity = Frodo::Entity.new(options)
+      entity.instance_eval do
+        service.properties_for_entity(type).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 [Frodo::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'])
+      p json
+      p options
+      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 [Frodo::Entity]
+    def self.from_xml(xml_doc, options = {})
+      return nil if xml_doc.nil?
+      entity = Frodo::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: 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
+      schema.primary_key_for(name)
+    end
+
+    def is_new?
+      self[primary_key].nil?
+    end
+
+    def any_errors?
+      !errors.empty?
+    end
+
+    def service
+      @service ||= Frodo::ServiceRegistry[service_name]
+    end
+
+    def schema
+      @schema ||= service.schemas[namespace]
+    end
+
+    private
+
+    def instantiate_property(property_name, value_xml)
+      prop_type = schema.get_property_type(name, property_name)
+      prop_type, value_type = prop_type.split(/\(|\)/)
+
+      if prop_type == 'Collection'
+        klass = ::Frodo::Properties::Collection
+        options = { value_type: value_type }
+      else
+        klass = ::Frodo::PropertyRegistry[prop_type]
+        options = {}
+      end
+
+      if klass.nil?
+        raise RuntimeError, "Unknown property type: #{prop_type}"
+      else
+        klass.from_xml(value_xml, options.merge(service: service))
+      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) || {}
+        schema.navigation_properties[name].each do |nav_name, details|
+          p nav_name
+          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) || {}
+        schema.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

data/lib/frodo/entity_container.rb

@@ -0,0 +1,75 @@
+module Frodo
+  #
+  class EntityContainer
+    # The EntityContainer's parent service
+    attr_reader :service
+    # The EntityContainer's metadata
+    attr_reader :metadata
+
+    # Creates a new EntityContainer
+    # @param service [Frodo::Service] The entity container's parent service
+    def initialize(service)
+      @metadata = service.metadata.xpath('//EntityContainer').first
+      @service  = service
+    end
+
+    # The EntityContainer's surrounding Schema
+    # @return [Nokogiri::XML]
+    def schema
+      @schema ||= metadata.ancestors('Schema').first
+    end
+
+    # Returns the EntityContainer's namespace.
+    # @return [String]
+    def namespace
+      @namespace ||= schema.attributes['Namespace'].value
+    end
+
+    # Returns the EntityContainer's name.
+    # @return [String]
+    def name
+      @name ||= metadata.attributes['Name'].value
+    end
+
+    # Returns a hash of EntitySet names and their respective EntityTypes.
+    # @return [Hash<String, String>]
+    def entity_sets
+      @entity_sets ||= metadata.xpath('//EntitySet').map do |entity|
+        [
+          entity.attributes['Name'].value,
+          entity.attributes['EntityType'].value
+        ]
+      end.to_h
+    end
+
+    # Retrieves the EntitySet associated with a specific EntityType by name
+    #
+    # @param entity_set_name [to_s] the name of the EntitySet desired
+    # @return [Frodo::EntitySet] an Frodo::EntitySet to query
+    def [](entity_set_name)
+      xpath_query = "//EntitySet[@Name='#{entity_set_name}']"
+      entity_set_node = metadata.xpath(xpath_query).first
+      raise ArgumentError, "Unknown Entity Set: #{entity_set_name}" if entity_set_node.nil?
+      entity_type = entity_set_node.attributes['EntityType'].value
+      Frodo::EntitySet.new(
+        name: entity_set_name,
+        namespace: namespace,
+        type: entity_type,
+        service_name: service.name,
+        container: name
+      )
+    end
+
+    def singletons
+      # TODO return singletons exposed by this EntityContainer
+    end
+
+    def actions
+      # TODO return action imports exposed by this EntityContainer
+    end
+
+    def functions
+      # TODO return function imports exposed by this EntityContainer
+    end
+  end
+end

data/lib/frodo/entity_set.rb

@@ -0,0 +1,131 @@
+module Frodo
+  # This class represents a set of entities within an Frodo service. It is
+  # instantiated whenever an Frodo::Service is asked for an EntitySet via the
+  # Frodo::Service#[] method call. It also provides Enumerable behavior so that
+  # you can interact with the entities within a set in a very comfortable way.
+  #
+  # This class also implements a query interface for finding certain entities
+  # based on query criteria or limiting the result set returned by the set. This
+  # functionality is implemented through transparent proxy objects.
+  class EntitySet
+    include Enumerable
+
+    # The name of the EntitySet
+    attr_reader :name
+    # The Entity type for the EntitySet
+    attr_reader :type
+    # The Frodo::Service's namespace
+    attr_reader :namespace
+    # The Frodo::Service's identifiable name
+    attr_reader :service_name
+    # The EntitySet's container name
+    attr_reader :container
+
+    # Sets up the EntitySet to permit querying for the resources in the set.
+    #
+    # @param options [Hash] the options to setup the EntitySet
+    # @return [Frodo::EntitySet] an instance of the EntitySet
+    def initialize(options = {})
+      @name         = options[:name]
+      @type         = options[:type]
+      @namespace    = options[:namespace]
+      @service_name = options[:service_name]
+      @container    = options[:container]
+    end
+
+    # Provided for Enumerable functionality
+    #
+    # @param block [block] a block to evaluate
+    # @return [Frodo::Entity] each entity in turn from this set
+    # def each(&block)
+    #   query.execute.each(&block)
+    # end
+
+    # # Return the first `n` Entities for the set.
+    # # If count is 1 it returns the single entity, otherwise its an array of entities
+    # # @return [Frodo::EntitySet]
+    # def first(count = 1)
+    #   result = query.limit(count).execute
+    #   count == 1 ? result.first : result.to_a
+    # end
+
+    # # Returns the number of entities within the set.
+    # # Not supported in Microsoft CRM2011
+    # # @return [Integer]
+    # def count
+    #   query.count
+    # end
+
+    # Create a new Entity for this set with the given properties.
+    # @param properties [Hash] property name as key and it's initial value
+    # @return [Frodo::Entity]
+    def new_entity(properties = {})
+      Frodo::Entity.with_properties(properties, entity_options)
+    end
+
+    # Returns a query targetted at the current EntitySet.
+    # @param options [Hash] query options
+    # @return [Frodo::Query]
+    def query(options = {})
+      Frodo::Query.new(self, options)
+    end
+
+
+    def entity_primary_key()
+      new_entity.primary_key
+    end
+
+    # Find the Entity with the supplied key value.
+    # @param key [to_s] primary key to lookup
+    # @return [Frodo::Entity,nil]
+    # def [](key, options={})
+    #   properties_to_expand = if options[:expand] == :all
+    #     new_entity.navigation_property_names
+    #   else
+    #     [ options[:expand] ].compact.flatten
+    #   end
+
+    #   query.expand(*properties_to_expand).find(key)
+    # end
+
+    # Write supplied entity back to the service.
+    # TODO Test this more with CRM2011
+    # @param entity [Frodo::Entity] entity to save or update in the service
+    # @return [Frodo::Entity]
+    # def <<(entity)
+    #   url_chunk, options = setup_entity_post_request(entity)
+
+    #   result = execute_entity_post_request(options, url_chunk)
+    #   if entity.is_new?
+    #     doc = ::Nokogiri::XML(result.body).remove_namespaces!
+    #     primary_key_node = doc.xpath("//content/properties/#{entity.primary_key}").first
+    #     entity[entity.primary_key] = primary_key_node.content unless primary_key_node.nil?
+    #   end
+
+    #   unless result.status.to_s =~ /^2[0-9][0-9]$/
+    #     entity.errors << ['could not commit entity']
+    #   end
+
+    #   entity
+    # end
+
+    # The Frodo::Service this EntitySet is associated with.
+    # @return [Frodo::Service]
+    # @api private
+    def service
+      @service ||= Frodo::ServiceRegistry[service_name]
+    end
+
+    # Options used for instantiating a new Frodo::Entity for this set.
+    # @return [Hash]
+    # @api private
+    def entity_options
+      {
+        service_name: service_name,
+        type:         type,
+        entity_set:   self
+      }
+    end
+
+  end
+end