frodata 0.9.1

data/lib/frodata/properties/number.rb

@@ -0,0 +1,14 @@
+module FrOData
+  module Properties
+    # Defines common behavior for FrOData numeric types.
+    module Number
+      private
+
+      def validate(value)
+        if value > max_value || value < min_value
+          validation_error "Value is outside accepted range: #{min_value} to #{max_value}"
+        end
+      end
+    end
+  end
+end

data/lib/frodata/properties/string.rb

@@ -0,0 +1,72 @@
+module FrOData
+  module Properties
+    # Defines the String FrOData type.
+    class String < FrOData::Property
+      # Returns the property value, properly typecast
+      # @return [String,nil]
+      def value
+        if (@value.nil? || @value.empty?) && allows_nil?
+          nil
+        else
+          encode_value(@value)
+        end
+      end
+
+      # Sets the property value
+      # @params new_value [to_s,nil]
+      def value=(new_value)
+        validate(new_value)
+        @value = new_value.nil? ? nil : encode_value(new_value.to_s)
+      end
+
+      # Value to be used in URLs.
+      # @return [String]
+      def url_value
+        "'#{value}'"
+      end
+
+      # The FrOData type name
+      def type
+        'Edm.String'
+      end
+
+      # Is the property value Unicode encoded
+      def is_unicode?
+        options[:unicode]
+      end
+
+      # Does the property have a default value
+      def has_default_value?
+        not(options[:default_value].nil?)
+      end
+
+      # The default value for the property
+      def default_value
+        options[:default_value]
+      end
+
+      private
+
+      def default_options
+        super.merge({
+          unicode: true,
+          default_value: nil
+        })
+      end
+
+      def validate(new_value)
+        if new_value.nil? && !allows_nil?
+          validation_error 'This property does not allow for nil values to be set'
+        end
+      end
+
+      def encode_value(new_value)
+        if options[:unicode]
+          new_value.encode(Encoding::UTF_8)
+        else
+          new_value.encode(Encoding::ASCII)
+        end
+      end
+    end
+  end
+end

data/lib/frodata/properties/time.rb

@@ -0,0 +1,40 @@
+module FrOData
+  module Properties
+    # Defines the Time FrOData type.
+    class Time < FrOData::Property
+      # Returns the property value, properly typecast
+      # @return [Time,nil]
+      def value
+        if (@value.nil? || @value.empty?) && allows_nil?
+          nil
+        else
+          ::Time.strptime(@value, '%H:%M:%S%:z')
+        end
+      end
+
+      # Sets the property value
+      # @params new_value [Time]
+      def value=(new_value)
+        validate(new_value)
+        @value = parse_value(new_value)
+      end
+
+      # The FrOData type name
+      def type
+        'Edm.Time'
+      end
+
+      private
+
+      def validate(value)
+        unless value.is_a?(::Time)
+          validation_error 'Value is not a time object'
+        end
+      end
+
+      def parse_value(value)
+        value.strftime('%H:%M:%S%:z')
+      end
+    end
+  end
+end

data/lib/frodata/properties/time_of_day.rb

@@ -0,0 +1,27 @@
+require 'frodata/properties/date_time'
+
+module FrOData
+  module Properties
+    # Defines the Date FrOData type.
+    class TimeOfDay < FrOData::Properties::DateTime
+      # The FrOData type name
+      def type
+        'Edm.TimeOfDay'
+      end
+
+      def url_value
+        @value
+      end
+
+      protected
+
+      def date_class
+        ::Time
+      end
+
+      def strptime_format
+        '%H:%M:%S.%L'
+      end
+    end
+  end
+end

data/lib/frodata/property.rb

@@ -0,0 +1,139 @@
+module FrOData
+  # FrOData::Property represents an abstract property, defining the basic
+  # interface and required methods, with some default implementations. All
+  # supported property types should be implemented under the FrOData::Properties
+  # namespace.
+  class Property
+    # The property's name
+    attr_reader :name
+    # The property's value
+    attr_accessor :value
+    # The property's options
+    attr_reader :options
+
+    # Default intialization for a property with a name, value and options.
+    # @param name [to_s]
+    # @param value [to_s,nil]
+    # @param options [Hash]
+    def initialize(name, value, options = {})
+      @name = name.to_s
+      @value = value.nil? ? nil : value.to_s
+      @options = default_options.merge(options)
+    end
+
+    # Abstract implementation, should return property type, based on
+    # FrOData::Service metadata in proper implementation.
+    # @raise NotImplementedError
+    def type
+      raise NotImplementedError
+    end
+
+    # Provides for value-based equality checking.
+    # @param other [value] object for comparison
+    # @return [Boolean]
+    def ==(other)
+      self.value == other.value
+    end
+
+    # Whether the property permits a nil value.
+    # (Default=true)
+    # @return [Boolean]
+    def allows_nil?
+      options[:allows_nil]
+    end
+
+    # Whether the property uses strict validation.
+    # (Default=false)
+    # @return [Boolean]
+    def strict?
+      if options.key? :strict
+        options[:strict]
+      elsif service
+        service.options[:strict]
+      else
+        true
+      end
+    end
+
+    # The configured concurrency mode for the property.
+    # @return [String]
+    def concurrency_mode
+      @concurrency_mode ||= options[:concurrency_mode]
+    end
+
+    # Value to be used in XML.
+    # @return [String]
+    def xml_value
+      @value
+    end
+
+    # Value to be used in JSON.
+    # @return [*]
+    def json_value
+      value
+    end
+
+    # Value to be used in URLs.
+    # @return [String]
+    def url_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,
+      }
+
+      if value.nil?
+        attributes['metadata:null'] = 'true'
+        xml_builder['data'].send(name.to_sym, attributes)
+      else
+        xml_builder['data'].send(name.to_sym, attributes, xml_value)
+      end
+    end
+
+    # Creates a new property instance from an XML element
+    # @param property_xml [Nokogiri::XML::Element]
+    # @param options [Hash]
+    # @return [FrOData::Property]
+    def self.from_xml(property_xml, options = {})
+      if property_xml.attributes['null'].andand.value == 'true'
+        content = nil
+      else
+        content = property_xml.content
+      end
+
+      new(property_xml.name, content, options)
+    end
+
+    protected
+
+    def default_options
+      {
+        allows_nil:       true,
+        concurrency_mode: :none
+      }
+    end
+
+    def service
+      options[:service]
+    end
+
+    def logger
+      # Use a dummy logger if service is not available (-> unit tests)
+      @logger ||= service.andand.logger || Logger.new('/dev/null')
+    end
+
+    def validation_error(message)
+      if strict?
+        raise ArgumentError, "#{name}: #{message}"
+      else
+        logger.warn "#{name}: #{message}"
+        nil
+      end
+    end
+  end
+end

data/lib/frodata/property_registry.rb

@@ -0,0 +1,41 @@
+require 'singleton'
+
+module FrOData
+  # Provides a registry for keeping track of various property types used by
+  # FrOData.
+  class PropertyRegistry
+    include Singleton
+
+    # Add a property type to the registry
+    #
+    # @param type_name [String] property type name to register
+    # @param klass [Class] Ruby class to use for the specified type
+    def add(type_name, klass)
+      properties[type_name] = klass
+    end
+
+    # Lookup a property by name and get the Ruby class to use for its instances
+    #
+    # @param type_name [String] the type name to lookup
+    # @return [Class, nil] the proper class or nil
+    def [](type_name)
+      properties[type_name]
+    end
+
+    # (see #add)
+    def self.add(type_name, klass)
+      FrOData::PropertyRegistry.instance.add(type_name, klass)
+    end
+
+    # (see #[])
+    def self.[](type_name)
+      FrOData::PropertyRegistry.instance[type_name]
+    end
+
+    private
+
+    def properties
+      @properties ||= {}
+    end
+  end
+end

data/lib/frodata/query.rb

@@ -0,0 +1,233 @@
+require 'frodata/query/criteria'
+require 'frodata/query/in_batches'
+
+module FrOData
+  # FrOData::Query provides the query interface for requesting Entities matching
+  # specific criteria from an FrOData::EntitySet. This class should not be
+  # instantiated directly, but can be. Normally you will access a Query by
+  # first asking for one from the FrOData::EntitySet you want to query.
+  class Query
+    attr_reader :options
+
+    include InBatches
+
+    # Create a new Query for the provided EntitySet
+    # @param entity_set [FrOData::EntitySet]
+    # @param options [Hash] Query options
+    def initialize(entity_set, options = {})
+      @entity_set = entity_set
+      @options    = options
+      setup_empty_criteria_set
+    end
+
+    # Instantiates an FrOData::Query::Criteria for the named property.
+    # @param property [to_s]
+    def [](property)
+      property_instance = @entity_set.new_entity.get_property(property)
+      property_instance = property if property_instance.nil?
+      FrOData::Query::Criteria.new(property: property_instance)
+    end
+
+    # Find the Entity with the supplied key value.
+    # @param key [to_s] primary key to lookup
+    # @return [FrOData::Entity,nil]
+    def find(key)
+      entity = @entity_set.new_entity
+      key_property = entity.get_property(entity.primary_key)
+      key_property.value = key
+
+      pathname = "#{entity_set.name}(#{key_property.url_value})"
+      query = [pathname, assemble_criteria].compact.join('?')
+      execute(query).first
+    end
+
+    # Adds a filter criteria to the query.
+    # For filter syntax see https://msdn.microsoft.com/en-us/library/gg309461.aspx
+    # Syntax:
+    #   Property Operator Value
+    #
+    # For example:
+    #   Name eq 'Customer Service'
+    #
+    # Operators:
+    # eq, ne, gt, ge, lt, le, and, or, not
+    #
+    # Value
+    #  can be 'null', can use single quotes
+    # @param criteria
+    def where(criteria)
+      criteria_set[:filter] << criteria
+      self
+    end
+
+    # Adds a fulltext search term to the query
+    # NOTE: May not be implemented by the service
+    # @param term [String]
+    def search(term)
+      criteria_set[:search] << term
+      self
+    end
+
+    # Adds a filter criteria to the query with 'and' logical operator.
+    # @param criteria
+    #def and(criteria)
+    #
+    #end
+
+    # Adds a filter criteria to the query with 'or' logical operator.
+    # @param criteria
+    #def or(criteria)
+    #
+    #end
+
+    # Specify properties to order the result by.
+    # Can use 'desc' like 'Name desc'
+    # @param properties [Array<Symbol>]
+    # @return [self]
+    def order_by(*properties)
+      criteria_set[:orderby] += properties
+      self
+    end
+
+    # Specify associations to expand in the result.
+    # @param associations [Array<Symbol>]
+    # @return [self]
+    def expand(*associations)
+      criteria_set[:expand] += associations
+      self
+    end
+
+    # Specify properties to select within the result.
+    # @param properties [Array<Symbol>]
+    # @return [self]
+    def select(*properties)
+      criteria_set[:select] += properties
+      self
+    end
+
+    # Add skip criteria to query.
+    # @param value [to_i]
+    # @return [self]
+    def skip(value)
+      criteria_set[:skip] = value.to_i
+      self
+    end
+
+    # Add limit criteria to query.
+    # @param value [to_i]
+    # @return [self]
+    def limit(value)
+      criteria_set[:top] = value.to_i
+      self
+    end
+
+    # Add inline count criteria to query.
+    # Not Supported in CRM2011
+    # @return [self]
+    def include_count
+      criteria_set[:inline_count] = true
+      self
+    end
+
+    # Convert Query to string.
+    # @return [String]
+    def to_s
+      [entity_set.name, assemble_criteria].compact.join('?')
+    end
+
+    # Execute the query.
+    # @return [FrOData::Service::Response]
+    def execute(url_chunk = self.to_s)
+      service.execute(url_chunk, options.merge(query: self))
+    end
+
+    # Executes the query to get a count of entities.
+    # @return [Integer]
+    def count
+      url_chunk = ["#{entity_set.name}/$count", assemble_criteria].compact.join('?')
+      response = self.execute(url_chunk)
+      # Some servers (*cough* Microsoft *cough*) seem to
+      # return extraneous characters in the response.
+      response.body.scan(/\d+/).first.to_i
+    end
+
+    # Checks whether a query will return any results by calling #count
+    # @return [Boolean]
+    def empty?
+      self.count == 0
+    end
+
+    # The EntitySet for this query.
+    # @return [FrOData::EntitySet]
+    # @api private
+    def entity_set
+      @entity_set
+    end
+
+    # The service for this query
+    # @return [FrOData::Service]
+    # @api private
+    def service
+      @service ||= entity_set.service
+    end
+
+    private
+
+    def criteria_set
+      @criteria_set
+    end
+
+    def setup_empty_criteria_set
+      @criteria_set = {
+        filter:       [],
+        search:       [],
+        select:       [],
+        expand:       [],
+        orderby:      [],
+        skip:         0,
+        top:          0,
+        inline_count: false
+      }
+    end
+
+    def assemble_criteria
+      criteria = [
+        filter_criteria,
+        search_criteria,
+        list_criteria(:orderby),
+        list_criteria(:expand),
+        list_criteria(:select),
+        inline_count_criteria,
+        paging_criteria(:skip),
+        paging_criteria(:top)
+      ].compact!
+
+      criteria.empty? ? nil : criteria.join('&')
+    end
+
+    def filter_criteria
+      return nil if criteria_set[:filter].empty?
+      filters = criteria_set[:filter].collect(&:to_s)
+      "$filter=#{filters.join(' and ')}"
+    end
+
+    def search_criteria
+      return nil if criteria_set[:search].empty?
+      filters = criteria_set[:search].collect(&:to_s)
+      "$search=#{filters.join(' AND ')}"
+    end
+
+    def list_criteria(name)
+      criteria_set[name].empty? ? nil : "$#{name}=#{criteria_set[name].join(',')}"
+    end
+
+    # inlinecount not supported by Microsoft CRM 2011
+    def inline_count_criteria
+      criteria_set[:inline_count] ? '$count=true' : nil
+    end
+
+    def paging_criteria(name)
+      criteria_set[name] == 0 ? nil : "$#{name}=#{criteria_set[name]}"
+    end
+  end
+end