activegraph 11.0.0.beta.1-java

data/lib/active_graph/shared/declared_properties.rb

@@ -0,0 +1,204 @@
+module ActiveGraph::Shared
+  # The DeclaredPropertyuManager holds details about objects created as a result of calling the #property
+  # class method on a class that includes ActiveGraph::Node or ActiveGraph::Relationship. There are many options
+  # that are referenced frequently, particularly during load and save, so this provides easy access and
+  # a way of separating behavior from the general Active{obj} modules.
+  #
+  # See ActiveGraph::Shared::DeclaredProperty for definitions of the property objects themselves.
+  class DeclaredProperties
+    include ActiveGraph::Shared::TypeConverters
+
+    attr_reader :klass
+    delegate :each, :each_pair, :each_key, :each_value, to: :registered_properties
+
+    # Each class that includes ActiveGraph::Node or ActiveGraph::Relationship gets one instance of this class.
+    # @param [#declared_properties] klass An object that has the #declared_properties method.
+    def initialize(klass)
+      @klass = klass
+    end
+
+    def [](key)
+      registered_properties[key.to_sym]
+    end
+
+    def property?(key)
+      registered_properties.key?(key.to_sym)
+    end
+
+    # @param [ActiveGraph::Shared::DeclaredProperty] property An instance of DeclaredProperty, created as the result of calling
+    # #property on an Node or Relationship class. The DeclaredProperty has specifics about the property, but registration
+    # makes the management object aware of it. This is necessary for type conversion, defaults, and inclusion in the nil and string hashes.
+    def register(property)
+      @_attributes_nil_hash = nil
+      @_attributes_string_map = nil
+      registered_properties[property.name] = property
+      register_magic_typecaster(property) if property.magic_typecaster
+      declared_property_defaults[property.name] = property.default_value if !property.default_value.nil?
+    end
+
+    def index_or_fail!(key, id_property_name, type = :exact)
+      return if key == id_property_name
+      fail "Cannot index undeclared property #{key}" unless property?(key)
+      registered_properties[key].index!(type)
+    end
+
+    def constraint_or_fail!(key, id_property_name, type = :unique)
+      return if key == id_property_name
+      fail "Cannot constraint undeclared property #{property}" unless property?(key)
+      registered_properties[key].constraint!(type)
+    end
+
+    # The :default option in ActiveGraph::Node#property class method allows for setting a default value instead of
+    # nil on declared properties. This holds those values.
+    def declared_property_defaults
+      @_default_property_values ||= {}
+    end
+
+    def registered_properties
+      @_registered_properties ||= {}
+    end
+
+    def indexed_properties
+      registered_properties.select { |_, p| p.index_or_constraint? }
+    end
+
+    # During object wrap, a hash is needed that contains each declared property with a nil value.
+    # The active_attr dependency is capable of providing this but it is expensive and calculated on the fly
+    # each time it is called. Rather than rely on that, we build this progressively as properties are registered.
+    # When the node or rel is loaded, this is used as a template.
+    def attributes_nil_hash
+      @_attributes_nil_hash ||= {}.tap do |attr_hash|
+        registered_properties.each_pair do |k, prop_obj|
+          val = prop_obj.default_value
+          attr_hash[k.to_s] = val
+        end
+      end.freeze
+    end
+
+    # During object wrapping, a props hash is built with string keys but ActiveGraph::Core provides symbols.
+    # Rather than a `to_s` or `symbolize_keys` during every load, we build a map of symbol-to-string
+    # to speed up the process. This increases memory used by the gem but reduces object allocation and GC, so it is faster
+    # in practice.
+    def attributes_string_map
+      @_attributes_string_map ||= {}.tap do |attr_hash|
+        attributes_nil_hash.each_key { |k| attr_hash[k.to_sym] = k }
+      end.freeze
+    end
+
+    # @param [Symbol] k A symbol for which the String representation is sought. This might seem silly -- we could just call #to_s --
+    # but when this happens many times while loading many objects, it results in a surprisingly significant slowdown.
+    # The branching logic handles what happens if a property can't be found.
+    # The first option attempts to find it in the existing hash.
+    # The second option checks whether the key is the class's id property and, if it is, the string hash is rebuilt with it to prevent
+    # future lookups.
+    # The third calls `to_s`. This would happen if undeclared properties are found on the object. We could add them to the string map
+    # but that would result in unchecked, un-GCed memory consumption. In the event that someone is adding properties dynamically,
+    # maybe through user input, this would be bad.
+    def string_key(k)
+      attributes_string_map[k] || string_map_id_property(k) || k.to_s
+    end
+
+    def unregister(name)
+      # might need to be include?(name.to_s)
+      fail ArgumentError, "Argument `#{name}` not an attribute" if not registered_properties[name]
+      registered_properties.delete(name)
+      unregister_magic_typecaster(name)
+      unregister_property_default(name)
+    end
+
+    def serialize(name, coder = JSON)
+      @serialize ||= {}
+      @serialize[name] = coder
+    end
+
+    def serialized_properties=(serialize_hash)
+      @serialized_property_keys = nil
+      @serialize = serialize_hash.clone
+    end
+
+    def serialized_properties
+      @serialize ||= {}
+    end
+
+    def serialized_properties_keys
+      @serialized_property_keys ||= serialized_properties.keys
+    end
+
+    def magic_typecast_properties_keys
+      @magic_typecast_properties_keys ||= magic_typecast_properties.keys
+    end
+
+    def magic_typecast_properties
+      @magic_typecast_properties ||= {}
+    end
+
+    EXCLUDED_TYPES = [Array, Range, Regexp]
+    def value_for_where(key, value)
+      return value unless prop = registered_properties[key]
+      return value_for_db(key, value) if prop.typecaster && prop.typecaster.convert_type == value.class
+
+      if should_convert_for_where?(key, value)
+        value_for_db(key, value)
+      else
+        value
+      end
+    end
+
+    def value_for_db(key, value)
+      return value unless registered_properties[key]
+      convert_property(key, value, :to_db)
+    end
+
+    def value_for_ruby(key, value)
+      return unless registered_properties[key]
+      convert_property(key, value, :to_ruby)
+    end
+
+    def inject_defaults!(object, props)
+      declared_property_defaults.each_pair do |k, v|
+        props[k.to_sym] = v.respond_to?(:call) ? v.call : v if object.send(k).nil? && props[k.to_sym].nil?
+      end
+      props
+    end
+
+    protected
+
+    # Prevents repeated calls to :_attribute_type, which isn't free and never changes.
+    def fetch_upstream_primitive(attr)
+      registered_properties[attr].type
+    end
+
+    private
+
+    def should_convert_for_where?(key, value)
+      (value.is_a?(Array) && supports_array?(key)) || !EXCLUDED_TYPES.include?(value.class)
+    end
+
+    # @param [Symbol] key An undeclared property value found in the _persisted_obj.properties hash.
+    # Typically, this is a node's id property, which will not be registered as other properties are.
+    # In the future, this should probably be reworked a bit. This class should either not know or care
+    # about the id property or it should be in charge of it. In the meantime, this improves
+    # node load performance.
+    def string_map_id_property(key)
+      return unless klass.id_property_name == key
+      key.to_s.tap do |string_key|
+        @_attributes_string_map = attributes_string_map.dup.tap { |h| h[key] = string_key }.freeze
+      end
+    end
+
+    def unregister_magic_typecaster(property)
+      magic_typecast_properties.delete(property)
+      @magic_typecast_properties_keys = nil
+    end
+
+    def unregister_property_default(property)
+      declared_property_defaults.delete(property)
+      @_default_property_values = nil
+    end
+
+    def register_magic_typecaster(property)
+      magic_typecast_properties[property.name] = property.magic_typecaster
+      @magic_typecast_properties_keys = nil
+    end
+  end
+end

data/lib/active_graph/shared/declared_property.rb

@@ -0,0 +1,109 @@
+module ActiveGraph::Shared
+  # Contains methods related to the management
+  class DeclaredProperty
+    include Comparable
+
+    class IllegalPropertyError < ActiveGraph::Error; end
+    include ActiveGraph::Shared::DeclaredProperty::Index
+
+    ILLEGAL_PROPS = %w(from_node to_node start_node end_node)
+    attr_reader :name, :name_string, :name_sym, :options, :magic_typecaster, :type, :typecaster, :default_value
+    alias default default_value
+
+    def initialize(name, options = {})
+      fail IllegalPropertyError, "#{name} is an illegal property" if ILLEGAL_PROPS.include?(name.to_s)
+      fail TypeError, "can't convert #{name.class} into Symbol" unless name.respond_to?(:to_sym)
+      @name = @name_sym = name.to_sym
+      @name_string = name.to_s
+      @type = options[:type]
+      @typecaster = options[:typecaster]
+      @default_value = options[:default]
+      @options = options
+      fail_invalid_options!
+    end
+
+    # Compare attribute definitions
+    #
+    # @example
+    #   attribute_definition <=> other
+    #
+    # @param [ActiveGraph::Shared::DeclaredProperty, Object] other The other
+    #   attribute definition to compare with.
+    #
+    # @return [-1, 0, 1, nil]
+    def <=>(other)
+      return nil unless other.instance_of? self.class
+      return nil if name == other.name && options != other.options
+      self.to_s <=> other.to_s
+    end
+
+    def inspect
+      options_description = options.map { |key, value| "#{key.inspect} => #{value.inspect}" }.sort.join(', ')
+      inspected_options = ", #{options_description}" unless options_description.empty?
+      "attribute :#{name}#{inspected_options}"
+    end
+
+    def to_s
+      name.to_s
+    end
+
+    def to_sym
+      name
+    end
+
+    def [](key)
+      respond_to?(key) ? public_send(key) : nil
+    end
+
+    def register
+      register_magic_properties
+    end
+
+    def fail_invalid_options!
+      case
+      when index?(:exact) && constraint?(:unique)
+        fail ActiveGraph::InvalidPropertyOptionsError,
+             "#Uniqueness constraints also provide exact indexes, cannot set both options on property #{name}"
+      end
+    end
+
+    private
+
+    def option_with_value!(key, value)
+      options[key] = value
+      fail_invalid_options!
+    end
+
+    def option_with_value?(key, value)
+      options[key] == value
+    end
+
+    # Tweaks properties
+    def register_magic_properties
+      @type ||= ActiveGraph::Config.timestamp_type if timestamp_prop?
+
+      register_magic_typecaster
+      register_type_converter
+    end
+
+    def timestamp_prop?
+      name.to_sym == :created_at || name.to_sym == :updated_at
+    end
+
+    def register_magic_typecaster
+      found_typecaster = ActiveGraph::Shared::TypeConverters.typecaster_for(type)
+      return unless found_typecaster && found_typecaster.respond_to?(:primitive_type)
+      @typecaster = found_typecaster
+      @magic_typecaster = type
+      @type = found_typecaster.primitive_type
+    end
+
+    def register_type_converter
+      converter = options[:serializer]
+      return unless converter
+      @type        = converter.convert_type
+      @typecaster  = ActiveGraph::Shared::TypeConverters::ObjectConverter
+      ActiveGraph::Shared::TypeConverters.register_converter(converter)
+    end
+  end
+end

data/lib/active_graph/shared/declared_property/index.rb

@@ -0,0 +1,37 @@
+module ActiveGraph::Shared
+  class DeclaredProperty
+    # None of these methods interact with the database. They only keep track of property settings in models.
+    # It could (should?) handle the actual indexing/constraining, but that's TBD.
+    module Index
+      def index_or_constraint?
+        index?(:exact) || constraint?(:unique)
+      end
+
+      def index?(type = :exact)
+        options.key?(:index) && options[:index] == type
+      end
+
+      def constraint?(type = :unique)
+        options.key?(:constraint) && options[:constraint] == type
+      end
+
+      def index!(type = :exact)
+        fail ActiveGraph::InvalidPropertyOptionsError, "Can't set index on constrainted property #{name} (constraints get indexes automatically)" if constraint?(:unique)
+        options[:index] = type
+      end
+
+      def constraint!(type = :unique)
+        fail ActiveGraph::InvalidPropertyOptionsError, "Can't set constraint on indexed property #{name} (constraints get indexes automatically)" if index?(:exact)
+        options[:constraint] = type
+      end
+
+      def unindex!(type = :exact)
+        options.delete(:index) if index?(type)
+      end
+
+      def unconstraint!(type = :unique)
+        options.delete(:constraint) if constraint?(type)
+      end
+    end
+  end
+end

data/lib/active_graph/shared/enum.rb

@@ -0,0 +1,167 @@
+module ActiveGraph::Shared
+  module Enum
+    extend ActiveSupport::Concern
+
+    class ConflictingEnumMethodError < ActiveGraph::Error; end
+    class InvalidEnumValueError < ActiveGraph::InvalidParameterError; end
+
+    module ClassMethods
+      attr_reader :neo4j_enum_data
+
+      # Similar to ActiveRecord enum, maps an integer value on the database to
+      # a set of enum keys.
+      #
+      # @example Base example
+      #   class Media
+      #     include ActiveGraph::Node
+      #     enum type: [:image, :video, :unknown]
+      #   end
+      #   Media.types # => { :images => 0, :video => 1, :unknown => 2 }
+      #
+      #   media.video!
+      #   media.image? # => false
+      #   media.type # => :video
+      #
+      #   Media.videos # => All medias with type = 1 (:video)
+      #   Media.where(type: :video) # => All medias with type = 1 (:video)
+      #
+      # @example Prefix-ing an enum
+      #   Media.enum type: [:image, :video, :unknown], _prefix: :enum
+      #
+      #   media.enum_video!
+      #   media.enum_video? # => true
+      #
+      # @example Suffix-ing an enum
+      #   Media.enum type: [:image, :video, :unknown], _suffix: true
+      #
+      #   media.video_type!
+      #   media.video_type? # => true
+      #
+      # @example Define a custom mapping for keys-numbers
+      #   Media.enum type: { image: 1, video: 2, unknown: 3 }
+      #
+      # @see http://edgeapi.rubyonrails.org/classes/ActiveRecord/Enum.html
+      def enum(parameters = {})
+        options, parameters = *split_options_and_parameters(parameters)
+        parameters.each do |property_name, enum_keys|
+          enum_keys = normalize_key_list enum_keys, options
+          @neo4j_enum_data ||= {}
+          @neo4j_enum_data[property_name] = enum_keys
+          define_property(property_name, enum_keys, options)
+          define_enum_methods(property_name, enum_keys, options)
+        end
+      end
+
+      protected
+
+      def normalize_key_list(enum_keys, options)
+        case_sensitive = options.fetch(:_case_sensitive, ActiveGraph::Config.enums_case_sensitive)
+
+        case enum_keys
+        when Hash
+          enum_keys
+        when Array
+          enum_keys = Hash[enum_keys.each_with_index.to_a]
+        else
+          fail ArgumentError, 'Invalid parameter for enum. Please provide an Array or an Hash.'
+        end
+
+        unless case_sensitive
+          enum_keys.each_key do |key|
+            fail ArgumentError, 'Enum keys must be lowercase unless _case_sensitive = true' unless key.downcase == key
+          end
+        end
+
+        enum_keys
+      end
+
+      VALID_OPTIONS_FOR_ENUMS = [:_index, :_prefix, :_suffix, :_default, :_case_sensitive]
+
+      def split_options_and_parameters(parameters)
+        options = {}
+        new_parameters = {}
+        parameters.each do |k, v|
+          if VALID_OPTIONS_FOR_ENUMS.include? k
+            options[k] = v
+          else
+            new_parameters[k] = v
+          end
+        end
+        [options, new_parameters]
+      end
+
+      def define_property(property_name, enum_keys, options)
+        property property_name, build_property_options(enum_keys, options)
+        serialize property_name, ActiveGraph::Shared::TypeConverters::EnumConverter.new(enum_keys, build_enum_options(enum_keys, options))
+
+        # If class has already been inherited, make sure subclasses fully inherit enum
+        subclasses.each do |klass|
+          klass.serialized_properties = self.serialized_properties
+        end
+      end
+
+      def build_property_options(_enum_keys, options = {})
+        {
+          default: options[:_default]
+        }
+      end
+
+      def build_enum_options(enum_keys, options = {})
+        if options[:_default] && not(enum_keys.include?(options[:_default]))
+          fail ArgumentError, 'Enum default value must match an enum key'
+        end
+
+        build_property_options(enum_keys, options).tap do |enum_options|
+          enum_options[:case_sensitive] = options[:_case_sensitive]
+        end
+      end
+
+      def define_enum_methods(property_name, enum_keys, options)
+        define_enum_methods_?(property_name, enum_keys, options)
+        define_enum_methods_!(property_name, enum_keys, options)
+        define_class_methods(property_name, enum_keys)
+      end
+
+      def define_class_methods(property_name, enum_keys)
+        plural_property_name = property_name.to_s.pluralize.to_sym
+        define_singleton_method(plural_property_name) do
+          enum_keys
+        end
+      end
+
+      def define_enum_methods_?(property_name, enum_keys, options)
+        enum_keys.each_key do |enum_value|
+          method_name = build_method_name(enum_value, property_name, options)
+          check_enum_method_conflicts! property_name, :"#{method_name}?"
+          define_method("#{method_name}?") do
+            __send__(property_name).to_s.to_sym == enum_value
+          end
+        end
+      end
+
+      def define_enum_methods_!(property_name, enum_keys, options)
+        enum_keys.each_key do |enum_value|
+          method_name = build_method_name(enum_value, property_name, options)
+          check_enum_method_conflicts! property_name, :"#{method_name}!"
+          define_method("#{method_name}!") do
+            __send__("#{property_name}=", enum_value)
+          end
+        end
+      end
+
+      def build_method_name(base_name, property_name, options)
+        method_name = base_name
+        method_name = "#{method_name}_#{property_name}" if options[:_suffix]
+        method_name = "#{options[:_prefix]}_#{method_name}" if options[:_prefix]
+        method_name
+      end
+
+      def check_enum_method_conflicts!(property_name, method_name)
+        fail ConflictingEnumMethodError,
+             "The enum `#{property_name}` is trying to define a `#{method_name}` method, "\
+             'that is already defined. Try to use options `:prefix` or `:suffix` '\
+             'to avoid conflicts.' if instance_methods(false).include?(method_name)
+      end
+    end
+  end
+end