frodata 0.9.1

data/lib/frodata/schema/complex_type.rb

@@ -0,0 +1,79 @@
+module FrOData
+  class Schema
+    # ComplexTypes are used in FrOData 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 [FrOData::Service]
+      def initialize(type_definition, schema)
+        @type_definition = type_definition
+        @schema          = schema
+      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, FrOData::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 < FrOData::Properties::Complex]
+      def property_class
+        @property_class ||= lambda { |type, complex_type|
+          klass = Class.new ::FrOData::Properties::Complex
+          klass.send(:define_method, :type) { type }
+          klass.send(:define_method, :complex_type) { complex_type }
+          klass
+        }.call(type, self)
+      end
+
+      private
+
+      def schema
+        @schema
+      end
+
+      def service
+        @schema.service
+      end
+
+      def type_definition
+        @type_definition
+      end
+
+      def collect_properties
+        Hash[type_definition.xpath('./Property').map do |property_xml|
+          property_name, property = schema.send(:process_property_from_xml, property_xml)
+          [property_name, property]
+        end]
+      end
+    end
+  end
+end

data/lib/frodata/schema/enum_type.rb

@@ -0,0 +1,95 @@
+module FrOData
+  class Schema
+    # Enumeration types are nominal types that represent a series of related values.
+    # Enumeration types expose these related values as members of the enumeration.
+    class EnumType
+      # Creates a new EnumType based on the supplied options.
+      # @param type_xml [Nokogiri::XML::Element]
+      # @param service [FrOData::Service]
+      # @return [self]
+      def initialize(type_definition, schema)
+        @type_definition = type_definition
+        @schema          = schema
+      end
+
+      # The name of the EnumType
+      # @return [String]
+      def name
+        options['Name']
+      end
+
+      # Returns the namespaced type for the EnumType.
+      # @return [String]
+      def type
+        "#{namespace}.#{name}"
+      end
+
+      # Whether this EnumType supports setting multiple values.
+      # @return [Boolean]
+      def is_flags?
+        options['IsFlags'] == 'true'
+      end
+
+      # The underlying type of this EnumType.
+      # @return [String]
+      def underlying_type
+        options['UnderlyingType'] || 'Edm.Int32'
+      end
+
+      # Returns the namespace this EnumType belongs to.
+      # @return [String]
+      def namespace
+        @namespace ||= service.namespace
+      end
+
+      # Returns the members of this EnumType and their values.
+      # @return [Hash]
+      def members
+        @members ||= collect_members
+      end
+
+      # Returns the property class that implements this `EnumType`.
+      # @return [Class < FrOData::Properties::Enum]
+      def property_class
+        @property_class ||= lambda { |type, members, is_flags|
+          klass = Class.new ::FrOData::Properties::Enum
+          klass.send(:define_method, :type) { type }
+          klass.send(:define_method, :members) { members }
+          klass.send(:define_method, :is_flags?) { is_flags }
+          klass
+        }.call(type, members, is_flags?)
+      end
+
+      # Returns the value of the requested member.
+      # @param member_name [to_s]
+      # @return [*]
+      def [](member_name)
+        members.invert[member_name.to_s]
+      end
+
+      private
+
+      def service
+        @schema.service
+      end
+
+      def type_definition
+        @type_definition
+      end
+
+      def options
+        @options = type_definition.attributes.map do |name, attr|
+          [name, attr.value]
+        end.to_h
+      end
+
+      def collect_members
+        Hash[type_definition.xpath('./Member').map.with_index do |member_xml, index|
+          member_name  = member_xml.attributes['Name'].value
+          member_value = member_xml.attributes['Value'].andand.value.andand.to_i
+          [member_value || index, member_name]
+        end]
+      end
+    end
+  end
+end

data/lib/frodata/service.rb

@@ -0,0 +1,254 @@
+require 'frodata/service/request'
+require 'frodata/service/response'
+
+module FrOData
+  # Encapsulates the basic details and functionality needed to interact with an
+  # FrOData service.
+  class Service
+    # The Faraday connection object used by the service to make requests
+    attr_reader :connection
+    # The FrOData Service's URL
+    attr_reader :service_url
+    # Service options
+    attr_reader :options
+
+    DEFAULT_TIMEOUT = 20
+
+    METADATA_TIMEOUTS = [20, 60]
+
+    MIME_TYPES = {
+      atom:  'application/atom+xml',
+      json:  'application/json',
+      xml:   'application/xml',
+      plain: 'text/plain'
+    }
+
+    # Opens the service based on the requested URL and adds the service to
+    # {FrOData::Registry}
+    #
+    # @param service_url [String|Faraday::Connection]
+    #   The URL to the desired FrOData service, or a Faraday connection object
+    # @param options [Hash] options to pass to the service
+    # @return [FrOData::Service] an instance of the service
+    def initialize(service_url, options = {}, &block)
+      if service_url.is_a? Faraday::Connection
+        @connection  = service_url
+        @service_url = connection.url_prefix
+      else
+        @service_url = service_url
+        @connection  = Faraday.new(service_url, options[:connection], &block)
+      end
+      @options     = default_options.merge(options)
+      FrOData::ServiceRegistry.add(self)
+      register_custom_types
+    end
+
+    # Opens the service based on the requested URL and adds the service to
+    # {FrOData::Registry}
+    # @deprecated Use {Service.new} instead.
+    #
+    # @param service_url [String] the URL to the desired FrOData service
+    # @param options [Hash] options to pass to the service
+    # @return [FrOData::Service] an instance of the service
+    def self.open(service_url, options = {}, &block)
+      Service.new(service_url, options, &block)
+    end
+
+    # Returns user supplied name for service, or its URL
+    # @return [String]
+    def name
+      @name ||= options[:name] || service_url
+    end
+
+    # Returns the service's metadata URL.
+    # @return [String]
+    def metadata_url
+      "#{service_url}/$metadata"
+    end
+
+    # Returns the service's metadata definition.
+    # @return [Nokogiri::XML]
+    def metadata
+      @metadata ||= lambda { read_metadata }.call
+    end
+
+    # Returns all of the service's schemas.
+    # @return Hash<String, FrOData::Schema>
+    def schemas
+      @schemas ||= metadata.xpath('//Schema').map do |schema_xml|
+        [
+          schema_xml.attributes['Namespace'].value,
+          Schema.new(schema_xml, self)
+        ]
+      end.to_h
+    end
+
+    # Returns the service's EntityContainer (singleton)
+    # @return FrOData::EntityContainer
+    def entity_container
+      @entity_container ||= EntityContainer.new(self)
+    end
+
+    # Returns a hash of EntitySet names and their respective EntityType names
+    # @return Hash<String, String>
+    def entity_sets
+      entity_container.entity_sets
+    end
+
+    # Retrieves the EntitySet associated with a specific EntityType by name
+    #
+    # @param entity_set_name [to_s] the name of the EntitySet desired
+    # @return [FrOData::EntitySet] an FrOData::EntitySet to query
+    def [](entity_set_name)
+      entity_container[entity_set_name]
+    end
+
+    # Returns the default namespace, that is, the namespace of the schema
+    # that contains the service's EntityContainer.
+    # @return [String]
+    def namespace
+      entity_container.namespace
+    end
+
+    # Returns a list of `EntityType`s exposed by the service
+    # @return Array<String>
+    def entity_types
+      @entity_types ||= schemas.map do |namespace, schema|
+        schema.entity_types.map do |entity_type|
+          "#{namespace}.#{entity_type}"
+        end
+      end.flatten
+    end
+
+    # Returns a list of `ComplexType`s used by the service.
+    # @return [Hash<String, FrOData::Schema::ComplexType>]
+    def complex_types
+      @complex_types ||= schemas.map do |namespace, schema|
+        schema.complex_types.map do |name, complex_type|
+          [ "#{namespace}.#{name}", complex_type ]
+        end.to_h
+      end.reduce({}, :merge)
+    end
+
+    # Returns a list of `EnumType`s used by the service
+    # @return [Hash<String, FrOData::Schema::EnumType>]
+    def enum_types
+      @enum_types ||= schemas.map do |namespace, schema|
+        schema.enum_types.map do |name, enum_type|
+          [ "#{namespace}.#{name}", enum_type ]
+        end.to_h
+      end.reduce({}, :merge)
+    end
+
+    # Returns a more compact inspection of the service object
+    def inspect
+      "#<#{self.class.name}:#{self.object_id} name='#{name}' service_url='#{self.service_url}'>"
+    end
+
+    # Execute a request against the service
+    #
+    # @param url_chunk [to_s] string to append to service URL
+    # @param options [Hash] additional request options
+    # @return [FrOData::Service::Response]
+    def execute(url_chunk, options = {})
+      Request.new(self, url_chunk, options).execute
+    end
+
+    # Get the property type for an entity from metadata.
+    #
+    # @param entity_name [to_s] the fully qualified entity name
+    # @param property_name [to_s] the property name needed
+    # @return [String] the name of the property's type
+    def get_property_type(entity_name, property_name)
+      namespace, _, entity_name = entity_name.rpartition('.')
+      raise ArgumentError, 'Namespace missing' if namespace.nil? || namespace.empty?
+      schemas[namespace].get_property_type(entity_name, property_name)
+    end
+
+    # Get the primary key for the supplied Entity.
+    #
+    # @param entity_name [to_s] The fully qualified entity name
+    # @return [String]
+    def primary_key_for(entity_name)
+      namespace, _, entity_name = entity_name.rpartition('.')
+      raise ArgumentError, 'Namespace missing' if namespace.nil? || namespace.empty?
+      schemas[namespace].primary_key_for(entity_name)
+    end
+
+    # Get the list of properties and their various options for the supplied
+    # Entity name.
+    # @param entity_name [to_s]
+    # @return [Hash]
+    # @api private
+    def properties_for_entity(entity_name)
+      namespace, _, entity_name = entity_name.rpartition('.')
+      raise ArgumentError, 'Namespace missing' if namespace.nil? || namespace.empty?
+      schemas[namespace].properties_for_entity(entity_name)
+    end
+
+    # Returns the logger instance used by the service.
+    # When Ruby on Rails has been detected, the service will
+    # use `Rails.logger`. The log level will NOT be changed.
+    #
+    # When no Rails has been detected, a default logger will
+    # be used that logs to STDOUT with the log level supplied
+    # via options, or the default log level if none was given.
+    # @return [Logger]
+    def logger
+      @logger ||= options[:logger] || if defined?(Rails)
+        Rails.logger
+      else
+        default_logger
+      end
+    end
+
+    # Allows the logger to be set to a custom `Logger` instance.
+    # @param custom_logger [Logger]
+    def logger=(custom_logger)
+      @logger = custom_logger
+    end
+
+    private
+
+    def default_options
+      {
+        request: {
+          timeout: DEFAULT_TIMEOUT
+        },
+        strict: true # strict property validation
+      }
+    end
+
+    def default_logger
+      Logger.new(STDOUT).tap do |logger|
+        logger.level = options[:log_level] || Logger::WARN
+      end
+    end
+
+    def read_metadata
+      # From file, good for debugging
+      if options[:metadata_file]
+        data = File.read(options[:metadata_file])
+        ::Nokogiri::XML(data).remove_namespaces!
+      else # From a URL
+        response = nil
+        METADATA_TIMEOUTS.each do |timeout|
+          response = execute(metadata_url, timeout: timeout)
+          break unless response.timed_out?
+        end
+        raise "Metadata Timeout" if response.timed_out?
+        ::Nokogiri::XML(response.body).remove_namespaces!
+      end
+    end
+
+    def register_custom_types
+      complex_types.each do |name, type|
+        ::FrOData::PropertyRegistry.add(name, type.property_class)
+      end
+
+      enum_types.each do |name, type|
+        ::FrOData::PropertyRegistry.add(name, type.property_class)
+      end
+    end
+  end
+end

data/lib/frodata/service/request.rb

@@ -0,0 +1,85 @@
+module FrOData
+  class Service
+    # Encapsulates a single request to an OData service.
+    class Request
+      # The OData service against which the request is performed
+      attr_reader :service
+      # The FrOData::Query that generated this request (optional)
+      attr_reader :query
+      # The HTTP method for this request
+      attr_accessor :method
+      # The request format (`:atom`, `:json`, or `:auto`)
+      attr_accessor :format
+
+      # Create a new request
+      # @param service [FrOData::Service] Where the request will be sent
+      # @param url_chunk [String] Request path, relative to the service URL, including query params
+      # @param options [Hash] Additional request options
+      def initialize(service, url_chunk, options = {})
+        @service = service
+        @url_chunk = url_chunk
+        @method = options.delete(:method) || :get
+        @format = options.delete(:format) || :auto
+        @query  = options.delete(:query)
+        @options = options
+      end
+
+      # Return the full request URL (including service base)
+      # @return [String]
+      def url
+        ::URI.join("#{service.service_url}/", ::URI.escape(url_chunk)).to_s
+      end
+
+      # The content type for this request. Depends on format.
+      # @return [String]
+      def content_type
+        if format == :auto
+          MIME_TYPES.values.join(',')
+        elsif MIME_TYPES.has_key? format
+          MIME_TYPES[format]
+        else
+          raise ArgumentError, "Unknown format '#{format}'"
+        end
+      end
+
+      # Execute the request
+      #
+      # @param additional_options [Hash] Request options to pass to Faraday
+      # @return [FrOData::Service::Response]
+      def execute(additional_options = {})
+        request_options = service.options[:request].merge(additional_options)
+
+        logger.info "Requesting #{method.to_s.upcase} #{url}..."
+        Response.new(service, query) do
+          connection.run_request(method, url_chunk, nil, headers) do |conn|
+            conn.options.merge! request_options
+          end
+        end
+      end
+
+      private
+
+      attr_reader :url_chunk
+
+      def connection
+        service.connection
+      end
+
+      def default_headers
+        {
+          'Accept'        => content_type,
+          'Content-Type'  => content_type,
+          'OData-Version' => '4.0'
+        }
+      end
+
+      def headers
+        default_headers.merge(@options[:headers] || {})
+      end
+
+      def logger
+        service.logger
+      end
+    end
+  end
+end